diff --git a/.gitignore b/.gitignore index 0f3c845e29..2b596375c5 100644 --- a/.gitignore +++ b/.gitignore @@ -77,6 +77,10 @@ docs/* !docs/screenshots/ !docs/i18n/ !docs/i18n/** +!docs/a2a-server.md +!docs/auto-combo.md +!docs/mcp-server.md +!docs/new-features/ # open-sse tests open-sse/test/* diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 90db235d9b..b795722c11 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -260,6 +260,16 @@ Response example: CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + ### Resilience & Rate Limits | Endpoint | Method | Description | diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 66d352e3cb..82cc73b67b 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -16,7 +16,7 @@ Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI) ## 🎨 Combos -Create model routing combos with 6 strategies: fill-first, round-robin, power-of-two-choices, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) @@ -46,9 +46,28 @@ Four modes for debugging API translations: **Playground** (format converter), ** --- +## 🎮 Model Playground _(v2.0.9+)_ + +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + ## ⚙️ Settings -General settings, system storage, backup management (export/import database), appearance (dark/light mode), security (includes API endpoint protection and custom provider blocking), routing (model aliases, background task degradation), resilience (rate limit persistence), and advanced configuration. +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) @@ -56,12 +75,29 @@ General settings, system storage, backup management (export/import database), ap ## 🔧 CLI Tools -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, and **GitHub Copilot** (config generator for `chatLanguageModels.json`). +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- +## 🤖 CLI Agents _(v2.0.11+)_ + +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + ## 📝 Request Logs Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. @@ -72,15 +108,27 @@ Real-time request logging with filtering by provider, model, account, and API ke ## 🌐 API Endpoint -Your unified API endpoint with capability breakdown: Chat Completions, Embeddings, Image Generation, Reranking, Audio Transcription, and registered API keys. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) --- +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + ## 🖥️ Desktop Application -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, and one-click install. +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. Key features: @@ -88,6 +136,7 @@ Key features: - System tray with port management - Content Security Policy - Single-instance lock +- Auto-update on restart - Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) 📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/TASKS.md b/docs/TASKS.md deleted file mode 100644 index 3ea8b535a5..0000000000 --- a/docs/TASKS.md +++ /dev/null @@ -1,113 +0,0 @@ -# Rate Limiting & Flow Control Overhaul — Tasks - -> Referência: [Relatório de Análise](../walkthrough.md) · Fase docs em `/docs/phases/` - ---- - -## Fase 1 — Error Classification & Provider Profiles - -### Backend Core - -- [x] `constants.ts` — Substituir `COOLDOWN_MS.transient` por `transientInitial` (5s) + `transientMax` (60s) -- [x] `constants.ts` — Adicionar `PROVIDER_PROFILES` (oauth / apikey) com cooldowns diferenciados -- [x] `constants.ts` — Adicionar `DEFAULT_API_LIMITS` (100 RPM, 200ms minTime) -- [x] `providerRegistry.ts` — Criar helper `getProviderCategory(providerId)` → `"oauth"` | `"apikey"` -- [x] `accountFallback.ts` — Aceitar `provider` como parâmetro em `checkFallbackError` -- [x] `accountFallback.ts` — Implementar backoff exponencial para 502/503/504 transientes -- [x] `accountFallback.ts` — Calcular cooldown baseado no perfil do provedor -- [x] `accountFallback.ts` — Adicionar helper `getProviderProfile(provider)` - -### Callers (propagar `provider`) - -- [x] `auth.ts` → `markAccountUnavailable` — Passar `provider` para `checkFallbackError` -- [x] `combo.ts` → `handleComboChat` / `handleRoundRobinCombo` — Passar `provider` nos erros - -### Testes - -- [x] Atualizar `rate-limit-enhanced.test.mjs` — Teste "transient errors don't increase backoff" → `newBackoffLevel = 1` -- [x] Criar `error-classification.test.mjs` — Cooldown exponencial 502, perfis OAuth/API, helper `getProviderCategory` - ---- - -## Fase 2 — Circuit Breaker no Combo Pipeline - -### Backend - -- [x] `combo.ts` — Importar `getCircuitBreaker` e `CircuitBreakerOpenError` -- [x] `combo.ts` — `handleComboChat` — Verificar `breaker.canExecute()` antes de cada modelo -- [x] `combo.ts` — `handleRoundRobinCombo` — Integrar breaker per-model -- [x] `combo.ts` — Marcar `semaphore.markRateLimited` para 502/503/504 (não só 429) -- [x] `combo.ts` — Implementar early exit quando todos os modelos têm breaker OPEN - -### Testes - -- [x] Criar `combo-circuit-breaker.test.mjs` — Combo skip breaker OPEN, early exit, semáforo 502 - ---- - -## Fase 3 — Anti-Thundering Herd & Auto Rate Limit - -### Backend - -- [x] `rateLimitManager.ts` — Auto-enable para `apikey` providers com limites elevados -- [x] `rateLimitManager.ts` — Criar limiter com defaults (100 RPM) quando não configurado -- [x] `auth.ts` — Adicionar mutex na `markAccountUnavailable` para evitar marcação paralela - -### Testes - -- [x] Criar `thundering-herd.test.mjs` — Mutex, auto-enable, limites não restritivos - ---- - -## Fase 4 — Frontend Resilience UI - -### Settings Page - -- [x] `settings/page.tsx` — Adicionar tab "Resilience" (icon: `health_and_safety`) entre Routing e Pricing - -### Novos Componentes - -- [x] Criar `ResilienceTab.tsx` — Layout com 4 cards (Provider Profiles → Rate Limiting → Circuit Breakers → Policies) -- [x] Criar `ProviderProfilesCard.tsx` — Toggle OAuth/API Key, inputs para cooldowns -- [x] Criar `CircuitBreakerCard.tsx` — Status real-time per-provider, auto-refresh 5s, botão reset -- [x] Criar `RateLimitOverviewCard.tsx` — Tabela providers × accounts × cooldown — **agora editável com RPM, Min Gap, Max Concurrent** - -### API Routes - -- [x] Criar `api/resilience/route.ts` — GET (estado completo + defaults mesclados) + PATCH (salvar perfis + defaults) -- [x] Criar `api/resilience/reset/route.ts` — POST (resetar breakers + cooldowns) - -### Migração - -- [x] `PoliciesPanel.tsx` movido de Security para Resilience tab - ---- - -## Fase 5 — Settings Page Restructure (v0.9.0) - -### Tab Reorganization - -- [x] **Security** — Simplificado para Login/Password + IP Access Control -- [x] **Routing** — Expandido para 6 estratégias globais com descrições -- [x] **Resilience** — Reordenado: Provider Profiles → Rate Limiting (editável) → Circuit Breakers → Policies -- [x] **AI** — Thinking Budget + System Prompt + Prompt Cache (movido do Advanced) -- [x] **Advanced** — Simplificado para apenas Global Proxy - -### Backend Routing Strategies - -- [x] `auth.ts` — Implementar `random` (Fisher-Yates shuffle) -- [x] `auth.ts` — Implementar `least-used` (sorted by lastUsedAt) -- [x] `auth.ts` — Implementar `cost-optimized` (sorted by priority) -- [x] `auth.ts` — Corrigir `p2c` (power-of-two-choices com health scoring) -- [x] `settings.ts` — Expandir tipo `fallbackStrategy` para 6 valores - ---- - -## Verificação Final - -- [x] Rodar todos os testes unitários: `node --test tests/unit/*.test.mjs` -- [x] Build do Next.js: `npm run build` -- [x] Verificar aba Resilience no browser -- [x] Testar persistência dos perfis (salvar → reload) -- [x] Testar Reset All Breakers -- [x] Verificar todas as 5 tabs reestruturadas diff --git a/docs/a2a-server.md b/docs/a2a-server.md new file mode 100644 index 0000000000..9d61dd1870 --- /dev/null +++ b/docs/a2a-server.md @@ -0,0 +1,196 @@ +# OmniRoute A2A Server Documentation + +> Agent-to-Agent Protocol v0.3 — OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` — Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` — SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` — Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` — Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted → working → completed + → failed + → cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/adr/ADR-001-nextjs-foundation.md b/docs/adr/ADR-001-nextjs-foundation.md deleted file mode 100644 index 8bb7637b18..0000000000 --- a/docs/adr/ADR-001-nextjs-foundation.md +++ /dev/null @@ -1,37 +0,0 @@ -# ADR-001: Next.js as the Foundation for an AI Gateway - -## Status: Accepted - -## Context - -OmniRoute is an AI routing gateway that translates, forwards, and manages requests across 20+ LLM providers. We needed a framework that could serve both the API proxy layer and a management dashboard from a single codebase. - -**Alternatives considered:** - -- **Express.js only** — Simpler proxy, but requires separate frontend tooling -- **Fastify** — Fast, but no built-in SSR/dashboard support -- **Next.js** — Unified full-stack framework with API routes, SSR, and static pages - -## Decision - -We chose Next.js because: - -1. **Single deployment** — API routes (`/api/*`) and dashboard UI in one process -2. **Middleware layer** — Native request interception for auth guards and request tracing -3. **File-based routing** — Easy to map provider endpoints to handlers -4. **Built-in TypeScript** — Type safety across the entire codebase - -## Consequences - -**Positive:** - -- One `npm run build` produces both API and UI -- Middleware provides centralized auth and request tracing -- Dashboard gets automatic code splitting and optimization - -**Negative:** - -- Next.js middleware has limitations (no heavy imports, edge runtime constraints) -- Serverless deployment model doesn't align with persistent WebSocket/SSE connections -- Build times are longer than Express-only setups -- The SSE proxy layer (`open-sse/`) operates outside Next.js conventions diff --git a/docs/adr/ADR-002-hub-spoke-translation.md b/docs/adr/ADR-002-hub-spoke-translation.md deleted file mode 100644 index bca315769c..0000000000 --- a/docs/adr/ADR-002-hub-spoke-translation.md +++ /dev/null @@ -1,37 +0,0 @@ -# ADR-002: Hub-and-Spoke Translation with OpenAI as Intermediate Format - -## Status: Accepted - -## Context - -OmniRoute routes requests across 20+ providers, each with its own API format (OpenAI, Anthropic Messages, Google Gemini, AWS Bedrock, etc.). Direct provider-to-provider translation would require O(n²) translators. - -**Alternatives considered:** - -- **Direct translation** — Each pair needs a dedicated translator (n² complexity) -- **Common intermediate format** — Translate to/from a canonical format (2n complexity) -- **Protocol buffers** — Strong typing but heavy overhead for a proxy - -## Decision - -We use the **OpenAI Chat Completions format** as the canonical intermediate representation. All incoming requests are normalized to OpenAI format, processed, then translated to the target provider's format. - -``` -Client → [any format] → OpenAI canonical → [target format] → Provider -Provider → [response] → OpenAI canonical → [original format] → Client -``` - -## Consequences - -**Positive:** - -- Only 2 translators per provider (inbound + outbound) instead of n² pairs -- OpenAI format is the de facto standard — most clients already use it -- Adding a new provider requires only implementing one translator pair -- Streaming (SSE) works consistently through the canonical format - -**Negative:** - -- Some provider-specific features may be lost in translation -- The double translation adds latency (typically < 5ms) -- OpenAI format changes require updating the canonical representation diff --git a/docs/adr/ADR-003-dual-storage-sqlite.md b/docs/adr/ADR-003-dual-storage-sqlite.md deleted file mode 100644 index 5b68c15fbb..0000000000 --- a/docs/adr/ADR-003-dual-storage-sqlite.md +++ /dev/null @@ -1,39 +0,0 @@ -# ADR-003: Dual Storage — SQLite Primary with JSON Migration Path - -## Status: Accepted - -## Context - -OmniRoute originally used LowDB (JSON file) for all persistence. As the project grew, JSON-based storage became a bottleneck for concurrent access, querying, and data integrity. - -**Alternatives considered:** - -- **LowDB only** — Simple but no concurrent access, no ACID, no querying -- **SQLite only** — Fast, ACID-compliant, but breaks existing deployments -- **PostgreSQL** — Production-grade but requires external dependency -- **Dual storage with migration** — SQLite primary + automatic JSON migration - -## Decision - -We migrated to **SQLite as the primary store** with an automatic one-time migration from `db.json`: - -1. On startup, if `db.json` exists and SQLite is empty, auto-migrate all data -2. All new reads/writes go through SQLite -3. The `db.json` file is preserved but no longer written to - -Settings remain in a hybrid model where LowDB handles simple key-value configuration for backward compatibility. - -## Consequences - -**Positive:** - -- ACID transactions for provider connections, API keys, and usage data -- Proper SQL queries for analytics and log filtering -- Concurrent read/write safety via WAL mode -- Zero-downtime migration from JSON — users upgrade transparently - -**Negative:** - -- Two storage engines to maintain (SQLite + LowDB for settings) -- Migration code must handle edge cases and partial data -- SQLite binary dependency needed in deployment environments diff --git a/docs/auto-combo.md b/docs/auto-combo.md new file mode 100644 index 0000000000..afa5463279 --- /dev/null +++ b/docs/auto-combo.md @@ -0,0 +1,63 @@ +# OmniRoute Auto-Combo Engine + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model × task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| 🚀 **Ship Fast** | Speed | latencyInv: 0.35 | +| 💰 **Cost Saver** | Economy | costInv: 0.40 | +| 🎯 **Quality First** | Best model | taskFit: 0.40 | +| 📡 **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 → excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN → auto-excluded; HALF_OPEN → probe requests +- **Incident mode**: >50% OPEN → disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` → high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model × task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n-tasks/01-home.md b/docs/i18n-tasks/01-home.md deleted file mode 100644 index 84b7765f1b..0000000000 --- a/docs/i18n-tasks/01-home.md +++ /dev/null @@ -1,36 +0,0 @@ -# Task 01 — Home Page (Dashboard) - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `home` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/page.tsx` | 17 | 0 (wrapper) | -| `src/app/(dashboard)/dashboard/HomePageClient.tsx` | 500 | ~25 | - -## Strings a Traduzir - -### HomePageClient.tsx -| Linha | String EN | Chave i18n | String PT-BR | -|-------|-----------|------------|--------------| -| 138 | "Quick Start" | `home.quickStart` | "Início Rápido" | -| 242 | "Providers Overview" | `home.providersOverview` | "Visão Geral dos Provedores" | -| 436 | "No models available for this provider." | `home.noModelsAvailable` | "Nenhum modelo disponível para este provedor." | -| — | "Total Requests" | `home.totalRequests` | "Total de Requisições" | -| — | "Active Providers" | `home.activeProviders` | "Provedores Ativos" | -| — | "Success Rate" | `home.successRate` | "Taxa de Sucesso" | -| — | "Avg Latency" | `home.avgLatency` | "Latência Média" | -| — | "Configure Endpoint" | `home.configureEndpoint` | "Configurar Endpoint" | -| — | "Add Provider" | `home.addProvider` | "Adicionar Provedor" | -| — | "View Docs" | `home.viewDocs` | "Ver Documentação" | -| — | "Copied!" | `common.copied` | ✅ já existe | -| — | "requests" | `home.requests` | "requisições" | -| — | "models" | `home.models` | "modelos" | -| — | "accounts" | `home.accounts` | "contas" | - -## Checklist -- [ ] Adicionar chaves no `en.json` (namespace `home`) -- [ ] Adicionar traduções no `pt-BR.json` -- [ ] Substituir strings por `t()` no `HomePageClient.tsx` -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/02-analytics.md b/docs/i18n-tasks/02-analytics.md deleted file mode 100644 index b8f1f52efa..0000000000 --- a/docs/i18n-tasks/02-analytics.md +++ /dev/null @@ -1,25 +0,0 @@ -# Task 02 — Analytics Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `analytics` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/analytics/page.tsx` | 46 | ~8 | - -## Strings a Traduzir - -| Linha | String EN | Chave i18n | String PT-BR | -|-------|-----------|------------|--------------| -| 11 | "Monitor your API usage patterns..." | `analytics.overviewDescription` | "Monitore padrões de uso da API..." | -| 13 | "Run evaluation suites to test..." | `analytics.evalsDescription` | "Execute suítes de avaliação..." | -| 24 | "Analytics" | `analytics.title` | "Análises" | -| 32 | "Overview" | `analytics.overview` | "Visão Geral" | -| 33 | "Evals" | `analytics.evals` | "Avaliações" | - -## Checklist -- [ ] Adicionar chaves no `en.json` -- [ ] Adicionar traduções no `pt-BR.json` -- [ ] Substituir strings por `t()` em `page.tsx` -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/03-api-manager.md b/docs/i18n-tasks/03-api-manager.md deleted file mode 100644 index 95a225529e..0000000000 --- a/docs/i18n-tasks/03-api-manager.md +++ /dev/null @@ -1,31 +0,0 @@ -# Task 03 — API Manager Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `apiManager` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/api-manager/ApiManagerPageClient.tsx` | ~400 | ~20 | - -## Strings a Traduzir (levantamento parcial — abrir código para completar) - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "API Keys" | `apiManager.title` | "Chaves de API" | -| "Create API Key" | `apiManager.createKey` | "Criar Chave de API" | -| "Name" | `apiManager.name` | "Nome" | -| "Key" | `apiManager.key` | "Chave" | -| "Created" | `apiManager.created` | "Criado em" | -| "Last Used" | `apiManager.lastUsed` | "Último Uso" | -| "Actions" | `apiManager.actions` | "Ações" | -| "Delete" | `common.delete` | ✅ já existe | -| "No API keys found" | `apiManager.noKeys` | "Nenhuma chave de API encontrada" | -| ~11 strings adicionais | — | Levantar no código | - -## Checklist -- [ ] Levantar todas as strings do `ApiManagerPageClient.tsx` -- [ ] Adicionar chaves no `en.json` -- [ ] Adicionar traduções no `pt-BR.json` -- [ ] Substituir strings por `t()` -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/04-audit-log.md b/docs/i18n-tasks/04-audit-log.md deleted file mode 100644 index bf4ca8e981..0000000000 --- a/docs/i18n-tasks/04-audit-log.md +++ /dev/null @@ -1,31 +0,0 @@ -# Task 04 — Audit Log Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `auditLog` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/audit-log/page.tsx` | 241 | ~12 | -| `src/app/(dashboard)/dashboard/logs/AuditLogTab.tsx` | ~100 | ~3 | - -## Strings a Traduzir - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "Audit Log" | `auditLog.title` | "Log de Auditoria" | -| "Search actions..." | `auditLog.searchPlaceholder` | "Buscar ações..." | -| "Action" | `auditLog.action` | "Ação" | -| "Actor" | `auditLog.actor` | "Autor" | -| "Target" | `auditLog.target` | "Alvo" | -| "Details" | `auditLog.details` | "Detalhes" | -| "IP Address" | `auditLog.ipAddress` | "Endereço IP" | -| "Timestamp" | `auditLog.timestamp` | "Data/Hora" | -| "No audit entries found" | `auditLog.noEntries` | "Nenhum registro de auditoria" | -| "Load More" | `auditLog.loadMore` | "Carregar Mais" | - -## Checklist -- [ ] Adicionar chaves no `en.json` -- [ ] Adicionar traduções no `pt-BR.json` -- [ ] Substituir strings em `audit-log/page.tsx` e `AuditLogTab.tsx` -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/05-cli-tools.md b/docs/i18n-tasks/05-cli-tools.md deleted file mode 100644 index a7491fcd22..0000000000 --- a/docs/i18n-tasks/05-cli-tools.md +++ /dev/null @@ -1,37 +0,0 @@ -# Task 05 — CLI Tools Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `cliTools` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `cli-tools/components/AntigravityToolCard.tsx` | ~3 | -| `cli-tools/components/ClaudeToolCard.tsx` | ~3 | -| `cli-tools/components/ClineToolCard.tsx` | ~4 | -| `cli-tools/components/CodexToolCard.tsx` | ~3 | -| `cli-tools/components/DefaultToolCard.tsx` | ~3 | -| `cli-tools/components/DroidToolCard.tsx` | ~2 | -| `cli-tools/components/KiloToolCard.tsx` | ~4 | -| `cli-tools/components/OpenClawToolCard.tsx` | ~2 | - -## Strings comuns entre Tool Cards - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "Status" | `cliTools.status` | "Status" | -| "Connected" | `cliTools.connected` | "Conectado" | -| "Not Connected" | `cliTools.notConnected` | "Não Conectado" | -| "Configure" | `cliTools.configure` | "Configurar" | -| "Test Connection" | `cliTools.testConnection` | "Testar Conexão" | -| "Models" | `cliTools.models` | "Modelos" | -| "Map Models" | `cliTools.mapModels` | "Mapear Modelos" | -| "Save" | `common.save` | ✅ já existe | -| "Cancel" | `common.cancel` | ✅ já existe | - -## Checklist -- [ ] Levantar strings de cada ToolCard -- [ ] Adicionar chaves no `en.json` -- [ ] Adicionar traduções no `pt-BR.json` -- [ ] Substituir por `t()` em cada componente -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/06-combos.md b/docs/i18n-tasks/06-combos.md deleted file mode 100644 index c81b4f5c09..0000000000 --- a/docs/i18n-tasks/06-combos.md +++ /dev/null @@ -1,34 +0,0 @@ -# Task 06 — Combos Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `combos` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/combos/page.tsx` | ~1000 | ~20 | - -## Strings a Traduzir - -| Linha | String EN | Chave i18n | String PT-BR | -|-------|-----------|------------|--------------| -| 207 | "Combos" | `combos.title` | "Combos" | -| 372 | "No models" | `combos.noModels` | "Sem modelos" | -| 747 | "Routing Strategy" | `combos.routingStrategy` | "Estratégia de Roteamento" | -| 791 | "Models" | `combos.models` | "Modelos" | -| 807 | "No models added yet" | `combos.noModelsYet` | "Nenhum modelo adicionado" | -| 922 | "Max Retries" | `combos.maxRetries` | "Máximo de Tentativas" | -| 959 | "Timeout (ms)" | `combos.timeout` | "Timeout (ms)" | -| 977 | "Healthcheck" | `combos.healthcheck` | "Verificação de Saúde" | -| — | "Create Combo" | `combos.create` | "Criar Combo" | -| — | "Edit Combo" | `combos.edit` | "Editar Combo" | -| — | "Delete Combo" | `combos.deleteCombo` | "Excluir Combo" | -| — | "Add Model" | `combos.addModel` | "Adicionar Modelo" | -| — | "Priority" | `combos.priority` | "Prioridade" | -| — | "Fallback" | `combos.fallback` | "Fallback" | - -## Checklist -- [ ] Adicionar chaves no `en.json` -- [ ] Adicionar traduções no `pt-BR.json` -- [ ] Substituir strings por `t()` em `combos/page.tsx` -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/07-costs.md b/docs/i18n-tasks/07-costs.md deleted file mode 100644 index 65c82ad296..0000000000 --- a/docs/i18n-tasks/07-costs.md +++ /dev/null @@ -1,23 +0,0 @@ -# Task 07 — Costs Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `costs` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/costs/page.tsx` | ~200 | ~5 | - -## Strings a Traduzir - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "Costs" | `costs.title` | "Custos" | -| "Total Cost" | `costs.totalCost` | "Custo Total" | -| "Cost Breakdown" | `costs.breakdown` | "Detalhamento de Custos" | -| "No cost data" | `costs.noData` | "Sem dados de custo" | - -## Checklist -- [ ] Levantar strings completas do código -- [ ] Adicionar chaves no `en.json` / `pt-BR.json` -- [ ] Substituir por `t()` e testar diff --git a/docs/i18n-tasks/08-endpoint.md b/docs/i18n-tasks/08-endpoint.md deleted file mode 100644 index c0358d5414..0000000000 --- a/docs/i18n-tasks/08-endpoint.md +++ /dev/null @@ -1,30 +0,0 @@ -# Task 08 — Endpoint Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `endpoint` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/endpoint/EndpointPageClient.tsx` | ~750 | ~20 | - -## Strings a Traduzir - -| Linha | String EN | Chave i18n | String PT-BR | -|-------|-----------|------------|--------------| -| 320 | "API Endpoint" | `endpoint.title` | "Endpoint da API" | -| 403 | "Available Endpoints" | `endpoint.available` | "Endpoints Disponíveis" | -| 561 | "Cloud Proxy" | `endpoint.cloudProxy` | "Proxy na Nuvem" | -| 632 | "Note" | `endpoint.note` | "Nota" | -| 717 | "Warning" | `endpoint.warning` | "Aviso" | -| 740 | "Are you sure you want to disable cloud proxy?" | `endpoint.disableConfirm` | "Tem certeza que deseja desativar o proxy na nuvem?" | -| — | "Copy" | `common.copy` | ✅ já existe | -| — | "Base URL" | `endpoint.baseUrl` | "URL Base" | -| — | "Connected" | `endpoint.connected` | "Conectado" | -| — | "Enable" | `endpoint.enable` | "Ativar" | -| — | "Disable" | `endpoint.disable` | "Desativar" | - -## Checklist -- [ ] Levantar strings restantes -- [ ] Adicionar chaves no `en.json` / `pt-BR.json` -- [ ] Substituir por `t()` e testar diff --git a/docs/i18n-tasks/09-health.md b/docs/i18n-tasks/09-health.md deleted file mode 100644 index 13e45d338e..0000000000 --- a/docs/i18n-tasks/09-health.md +++ /dev/null @@ -1,30 +0,0 @@ -# Task 09 — Health Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `health` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/health/page.tsx` | ~350 | ~15 | - -## Strings a Traduzir - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "System Health" | `health.title` | "Saúde do Sistema" | -| "Healthy" | `health.healthy` | "Saudável" | -| "Degraded" | `health.degraded` | "Degradado" | -| "Down" | `health.down` | "Offline" | -| "Uptime" | `health.uptime` | "Tempo Ativo" | -| "Memory" | `health.memory` | "Memória" | -| "CPU" | `health.cpu` | "CPU" | -| "Database" | `health.database` | "Banco de Dados" | -| "Last Check" | `health.lastCheck` | "Última Verificação" | -| "Refresh" | `common.refresh` | ✅ já existe | -| ~5 strings adicionais | — | Levantar | - -## Checklist -- [ ] Levantar strings restantes -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` e testar diff --git a/docs/i18n-tasks/10-limits.md b/docs/i18n-tasks/10-limits.md deleted file mode 100644 index 29b0dfae8a..0000000000 --- a/docs/i18n-tasks/10-limits.md +++ /dev/null @@ -1,24 +0,0 @@ -# Task 10 — Limits Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `limits` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/limits/page.tsx` | ~150 | ~5 | - -## Strings a Traduzir - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "Limits & Quotas" | `limits.title` | "Limites e Cotas" | -| "Rate Limit" | `limits.rateLimit` | "Limite de Taxa" | -| "Provider" | `limits.provider` | "Provedor" | -| "Remaining" | `limits.remaining` | "Restante" | -| "Reset" | `limits.reset` | "Reiniciar" | - -## Checklist -- [ ] Levantar strings completas -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` e testar diff --git a/docs/i18n-tasks/11-logs.md b/docs/i18n-tasks/11-logs.md deleted file mode 100644 index 3b1ef1c40b..0000000000 --- a/docs/i18n-tasks/11-logs.md +++ /dev/null @@ -1,24 +0,0 @@ -# Task 11 — Logs Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `logs` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/logs/` | ~200 | ~5 | - -## Strings a Traduzir - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "Logs" | `logs.title` | "Logs" | -| "Request Logs" | `logs.requestLogs` | "Logs de Requisições" | -| "Proxy Logs" | `logs.proxyLogs` | "Logs do Proxy" | -| "Audit Log" | `logs.auditLog` | "Log de Auditoria" | -| "Console" | `logs.console` | "Console" | - -## Checklist -- [ ] Levantar strings completas -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` e testar diff --git a/docs/i18n-tasks/12-onboarding.md b/docs/i18n-tasks/12-onboarding.md deleted file mode 100644 index 1abbcdd253..0000000000 --- a/docs/i18n-tasks/12-onboarding.md +++ /dev/null @@ -1,26 +0,0 @@ -# Task 12 — Onboarding Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `onboarding` - -## Arquivos -| Arquivo | Linhas | Strings | -|---------|--------|---------| -| `src/app/(dashboard)/dashboard/onboarding/page.tsx` | ~300 | ~10 | - -## Strings a Traduzir - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "Welcome to OmniRoute" | `onboarding.welcome` | "Bem-vindo ao OmniRoute" | -| "Set Password" | `onboarding.setPassword` | "Definir Senha" | -| "Add Provider" | `onboarding.addProvider` | "Adicionar Provedor" | -| "Get Started" | `onboarding.getStarted` | "Começar" | -| "Skip" | `onboarding.skip` | "Pular" | -| "Next" | `common.next` | ✅ já existe | -| ~4 strings adicionais | — | Levantar | - -## Checklist -- [ ] Levantar strings completas -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` e testar diff --git a/docs/i18n-tasks/13-providers.md b/docs/i18n-tasks/13-providers.md deleted file mode 100644 index 6b376c58d2..0000000000 --- a/docs/i18n-tasks/13-providers.md +++ /dev/null @@ -1,35 +0,0 @@ -# Task 13 — Providers Pages - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `providers` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `providers/page.tsx` | ~5 | -| `providers/[id]/page.tsx` | ~12 | -| `providers/new/page.tsx` | ~3 | -| `providers/components/ModelAvailabilityPanel.tsx` | ~3 | -| `providers/components/ModelAvailabilityBadge.tsx` | ~1 | - -## Strings a Traduzir - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "Providers" | `providers.title` | "Provedores" | -| "Add Provider" | `providers.add` | "Adicionar Provedor" | -| "Edit Provider" | `providers.edit` | "Editar Provedor" | -| "Test Connection" | `providers.testConnection` | "Testar Conexão" | -| "Connected" | `providers.connected` | "Conectado" | -| "Disconnected" | `providers.disconnected` | "Desconectado" | -| "Models" | `providers.models` | "Modelos" | -| "Accounts" | `providers.accounts` | "Contas" | -| "Delete Provider" | `providers.deleteProvider` | "Excluir Provedor" | -| "No providers configured" | `providers.noProviders` | "Nenhum provedor configurado" | -| "Model Availability" | `providers.modelAvailability` | "Disponibilidade de Modelos" | -| ~9 strings adicionais | — | Levantar | - -## Checklist -- [ ] Levantar strings completas de todos os arquivos -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` e testar diff --git a/docs/i18n-tasks/14-settings.md b/docs/i18n-tasks/14-settings.md deleted file mode 100644 index b1344c39d6..0000000000 --- a/docs/i18n-tasks/14-settings.md +++ /dev/null @@ -1,51 +0,0 @@ -# Task 14 — Settings Page (MAIOR TAREFA) - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `settings` - -## Arquivos (20 componentes!) -| Arquivo | Strings | -|---------|---------| -| `settings/components/AppearanceTab.tsx` | ~4 | -| `settings/components/CacheStatsCard.tsx` | ~4 | -| `settings/components/ComboDefaultsTab.tsx` | ~8 | -| `settings/components/FallbackChainsEditor.tsx` | ~2 | -| `settings/components/IPFilterSection.tsx` | ~2 | -| `settings/components/PoliciesPanel.tsx` | ~5 | -| `settings/components/PricingTab.tsx` | ~8 | -| `settings/components/ProxyTab.tsx` | ~2 | -| `settings/components/ResilienceTab.tsx` | ~7 | -| `settings/components/RoutingTab.tsx` | ~4 | -| `settings/components/SecurityTab.tsx` | ~5 | -| `settings/components/SessionInfoCard.tsx` | ~5 | -| `settings/components/SystemPromptTab.tsx` | ~2 | -| `settings/components/SystemStorageTab.tsx` | ~8 | -| `settings/components/ThinkingBudgetTab.tsx` | ~5 | -| `settings/pricing/page.tsx` | ~17 | - -## Strings a Traduzir (amostra) - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "General" | `settings.general` | "Geral" | -| "Security" | `settings.security` | "Segurança" | -| "Appearance" | `settings.appearance` | "Aparência" | -| "Routing" | `settings.routing` | "Roteamento" | -| "Cache" | `settings.cache` | "Cache" | -| "Resilience" | `settings.resilience` | "Resiliência" | -| "System Prompt" | `settings.systemPrompt` | "Prompt do Sistema" | -| "Thinking Budget" | `settings.thinkingBudget` | "Orçamento de Raciocínio" | -| "Proxy" | `settings.proxy` | "Proxy" | -| "Pricing" | `settings.pricing` | "Preços" | -| "Storage" | `settings.storage` | "Armazenamento" | -| "Policies" | `settings.policies` | "Políticas" | -| "IP Filter" | `settings.ipFilter` | "Filtro de IP" | -| "Combo Defaults" | `settings.comboDefaults` | "Padrões de Combo" | -| "Fallback Chains" | `settings.fallbackChains` | "Cadeias de Fallback" | -| ~40 strings adicionais | — | Levantar em cada tab | - -## Checklist -- [ ] Levantar strings de CADA componente (16 arquivos) -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` em todos os 16 arquivos -- [ ] Testar cada aba em EN e PT-BR diff --git a/docs/i18n-tasks/15-translator.md b/docs/i18n-tasks/15-translator.md deleted file mode 100644 index 3a5199e781..0000000000 --- a/docs/i18n-tasks/15-translator.md +++ /dev/null @@ -1,41 +0,0 @@ -# Task 15 — Translator Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `translator` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `translator/components/LiveMonitorMode.tsx` | ~11 | -| `translator/components/PlaygroundMode.tsx` | ~5 | -| `translator/components/TestBenchMode.tsx` | ~3 | -| `translator/components/ChatTesterMode.tsx` | ~4 | - -## Strings a Traduzir - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "Real-Time Translation Activity" | `translator.realtime` | "Atividade de Tradução em Tempo Real" | -| "Chat Tester" | `translator.chatTester` | "Testador de Chat" | -| "Test Bench" | `translator.testBench` | "Bancada de Testes" | -| "Recent Translations" | `translator.recentTranslations` | "Traduções Recentes" | -| "No translations yet" | `translator.noTranslations` | "Nenhuma tradução ainda" | -| "Time" | `translator.time` | "Tempo" | -| "Source" | `translator.source` | "Origem" | -| "Target" | `translator.target` | "Destino" | -| "Model" | `translator.model` | "Modelo" | -| "Status" | `translator.status` | "Status" | -| "Latency" | `translator.latency` | "Latência" | -| "Format Converter" | `translator.formatConverter` | "Conversor de Formato" | -| "Input" | `translator.input` | "Entrada" | -| "Output" | `translator.output` | "Saída" | -| "Example Templates" | `translator.exampleTemplates` | "Modelos de Exemplo" | -| "Compatibility Tester" | `translator.compatibilityTester` | "Testador de Compatibilidade" | -| "Compatibility Report" | `translator.compatibilityReport` | "Relatório de Compatibilidade" | -| "Pipeline Debugger" | `translator.pipelineDebugger` | "Depurador de Pipeline" | -| "Translation Pipeline" | `translator.translationPipeline` | "Pipeline de Tradução" | - -## Checklist -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` em cada componente -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/16-usage.md b/docs/i18n-tasks/16-usage.md deleted file mode 100644 index 3921dc9a7c..0000000000 --- a/docs/i18n-tasks/16-usage.md +++ /dev/null @@ -1,57 +0,0 @@ -# Task 16 — Usage Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `usage` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `usage/components/BudgetTab.tsx` | ~4 | -| `usage/components/BudgetTelemetryCards.tsx` | ~9 | -| `usage/components/EvalsTab.tsx` | ~6 | -| `usage/components/RateLimitStatus.tsx` | ~2 | -| `usage/components/SessionsTab.tsx` | ~7 | -| `usage/components/ProviderLimits/index.tsx` | ~7 | -| `usage/components/ProviderLimits/ProviderLimitCard.tsx` | ~1 | -| `usage/components/ProviderLimits/QuotaTable.tsx` | ~1 | - -## Strings a Traduzir - -| String EN | Chave i18n | String PT-BR | -|-----------|------------|--------------| -| "Budget Management" | `usage.budgetManagement` | "Gerenciamento de Orçamento" | -| "API Key" | `usage.apiKey` | "Chave de API" | -| "This Month" | `usage.thisMonth` | "Este Mês" | -| "Set Limits" | `usage.setLimits` | "Definir Limites" | -| "Total requests" | `usage.totalRequests` | "Total de requisições" | -| "No data yet" | `usage.noData` | "Sem dados ainda" | -| "Entries" | `usage.entries` | "Entradas" | -| "Hit Rate" | `usage.hitRate` | "Taxa de Acerto" | -| "Circuit Breakers" | `usage.circuitBreakers` | "Disjuntores" | -| "Locked IPs" | `usage.lockedIPs` | "IPs Bloqueados" | -| "How It Works" | `usage.howItWorks` | "Como Funciona" | -| "Define" | `usage.define` | "Definir" | -| "Run" | `usage.run` | "Executar" | -| "Evaluate" | `usage.evaluate` | "Avaliar" | -| "Evaluation Suites" | `usage.evalSuites` | "Suítes de Avaliação" | -| "Model Evaluations" | `usage.modelEvals` | "Avaliações de Modelos" | -| "Model Lockouts" | `usage.modelLockouts` | "Bloqueios de Modelo" | -| "No models currently locked" | `usage.noLockouts` | "Nenhum modelo bloqueado" | -| "Active Sessions" | `usage.activeSessions` | "Sessões Ativas" | -| "No active sessions" | `usage.noSessions` | "Sem sessões ativas" | -| "Session" | `usage.session` | "Sessão" | -| "Age" | `usage.age` | "Idade" | -| "Requests" | `usage.requests` | "Requisições" | -| "Connection" | `usage.connection` | "Conexão" | -| "Provider Limits" | `usage.providerLimits` | "Limites do Provedor" | -| "No Providers Connected" | `usage.noProviders` | "Nenhum Provedor Conectado" | -| "Account" | `usage.account` | "Conta" | -| "Model Quotas" | `usage.modelQuotas` | "Cotas de Modelo" | -| "Last Used" | `usage.lastUsed` | "Último Uso" | -| "Actions" | `usage.actions` | "Ações" | -| "No quota data" | `usage.noQuota` | "Sem dados de cota" | - -## Checklist -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` em cada componente -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/17-shared-modals.md b/docs/i18n-tasks/17-shared-modals.md deleted file mode 100644 index c4c6743e09..0000000000 --- a/docs/i18n-tasks/17-shared-modals.md +++ /dev/null @@ -1,44 +0,0 @@ -# Task 17 — Shared Modals - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `modals` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `shared/components/OAuthModal.tsx` | ~6 | -| `shared/components/KiroAuthModal.tsx` | ~10 | -| `shared/components/KiroSocialOAuthModal.tsx` | ~3 | -| `shared/components/CursorAuthModal.tsx` | ~2 | -| `shared/components/PricingModal.tsx` | ~10 | -| `shared/components/ModelSelectModal.tsx` | ~2 | -| `shared/components/ProxyConfigModal.tsx` | ~1 | - -## Strings a Traduzir - -| String EN | String PT-BR | -|-----------|--------------| -| "Waiting for Authorization" | "Aguardando Autorização" | -| "Verification URL" | "URL de Verificação" | -| "Your Code" | "Seu Código" | -| "Remote access:" | "Acesso remoto:" | -| "Connected Successfully!" | "Conectado com Sucesso!" | -| "Connection Failed" | "Falha na Conexão" | -| "Choose your authentication method:" | "Escolha seu método de autenticação:" | -| "AWS Builder ID" | "AWS Builder ID" | -| "AWS IAM Identity Center" | "AWS IAM Identity Center" | -| "Google Account" | "Conta Google" | -| "GitHub Account" | "Conta GitHub" | -| "Import Token" | "Importar Token" | -| "Auto-detecting tokens..." | "Detectando tokens automaticamente..." | -| "Pricing Configuration" | "Configuração de Preços" | -| "Loading pricing data..." | "Carregando dados de preços..." | -| "Model" / "Input" / "Output" / "Cached" | "Modelo" / "Entrada" / "Saída" / "Em Cache" | -| "Combos" | "Combos" | -| "No models found" | "Nenhum modelo encontrado" | -| "Connected" | "Conectado" | - -## Checklist -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` em cada modal -- [ ] Testar cada modal em EN e PT-BR diff --git a/docs/i18n-tasks/18-shared-loggers.md b/docs/i18n-tasks/18-shared-loggers.md deleted file mode 100644 index 29dc5769c0..0000000000 --- a/docs/i18n-tasks/18-shared-loggers.md +++ /dev/null @@ -1,37 +0,0 @@ -# Task 18 — Shared Loggers - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `loggers` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `shared/components/RequestLoggerV2.tsx` | ~12 | -| `shared/components/RequestLoggerDetail.tsx` | ~4 | -| `shared/components/ProxyLogger.tsx` | ~7 | -| `shared/components/ProxyLogDetail.tsx` | ~6 | -| `shared/components/ConsoleLogViewer.tsx` | ~2 | - -## Strings a Traduzir - -| String EN | String PT-BR | -|-----------|--------------| -| "All Providers" | "Todos os Provedores" | -| "All Models" | "Todos os Modelos" | -| "All Accounts" | "Todas as Contas" | -| "All API Keys" | "Todas as Chaves de API" | -| "Newest" / "Oldest" | "Mais Recente" / "Mais Antigo" | -| "Model A-Z" / "Model Z-A" | "Modelo A-Z" / "Modelo Z-A" | -| "Columns" | "Colunas" | -| "Loading logs..." | "Carregando logs..." | -| "All Types" | "Todos os Tipos" | -| "All Levels" | "Todos os Níveis" | -| "Proxy Event" | "Evento do Proxy" | -| "Time" / "Model" / "Combo" | "Tempo" / "Modelo" / "Combo" | -| "No log entries found" | "Nenhuma entrada de log encontrada" | -| "No payload data available" | "Nenhum dado de payload disponível" | - -## Checklist -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` em cada logger -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/19-shared-charts.md b/docs/i18n-tasks/19-shared-charts.md deleted file mode 100644 index fac07cb072..0000000000 --- a/docs/i18n-tasks/19-shared-charts.md +++ /dev/null @@ -1,36 +0,0 @@ -# Task 19 — Shared Charts & Stats - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `stats` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `shared/components/UsageStats.tsx` | ~6 | -| `shared/components/analytics/charts.tsx` | ~15 | -| `shared/components/TokenHealthBadge.tsx` | ~6 | -| `shared/components/SystemMonitor.tsx` | ~1 | -| `shared/components/Footer.tsx` | ~3 | - -## Strings a Traduzir - -| String EN | String PT-BR | -|-----------|--------------| -| "Usage Overview" | "Visão Geral de Uso" | -| "Output Tokens" | "Tokens de Saída" | -| "Total Cost" | "Custo Total" | -| "Usage by Model" | "Uso por Modelo" | -| "Usage by Account" | "Uso por Conta" | -| "Failed to load usage statistics." | "Falha ao carregar estatísticas." | -| "Token Health" | "Saúde dos Tokens" | -| "Total OAuth" | "Total OAuth" | -| "Healthy" / "Errored" / "Warning" | "Saudável" / "Com Erro" / "Aviso" | -| "Last check" | "Última verificação" | -| "No data" / "Share" | "Sem dados" / "Compartilhar" | -| "Unable to load system metrics" | "Não foi possível carregar métricas" | -| "Product" / "Resources" / "Company" (Footer) | "Produto" / "Recursos" / "Empresa" | - -## Checklist -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` em cada componente -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/20-login-auth.md b/docs/i18n-tasks/20-login-auth.md deleted file mode 100644 index 5910266bcf..0000000000 --- a/docs/i18n-tasks/20-login-auth.md +++ /dev/null @@ -1,36 +0,0 @@ -# Task 20 — Login & Auth Pages - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `auth` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `src/app/login/page.tsx` | ~8 | -| `src/app/forgot-password/page.tsx` | ~3 | -| `src/app/callback/page.tsx` | ~5 | -| `src/app/forbidden/page.tsx` | ~1 | - -## Strings a Traduzir - -| String EN | String PT-BR | -|-----------|--------------| -| "Welcome" | "Bem-vindo" | -| "OmniRoute" | "OmniRoute" (não traduzir) | -| "Sign in" | "Entrar" | -| "Enter your password to continue" | "Digite sua senha para continuar" | -| "Password" | "Senha" | -| "Unified AI API Proxy" | "Proxy Unificado de API de IA" | -| "Loading..." | "Carregando..." | -| "Password protection is not enabled" | "Proteção por senha não está ativada" | -| "Reset Password" | "Redefinir Senha" | -| "Choose a method to recover access" | "Escolha um método para recuperar acesso" | -| "Processing..." | "Processando..." | -| "Authorization Successful!" | "Autorização bem-sucedida!" | -| "Copy This URL" | "Copiar esta URL" | -| "Access Denied" | "Acesso Negado" | - -## Checklist -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` em cada página -- [ ] Testar em EN e PT-BR diff --git a/docs/i18n-tasks/21-landing.md b/docs/i18n-tasks/21-landing.md deleted file mode 100644 index 8a0631d0d4..0000000000 --- a/docs/i18n-tasks/21-landing.md +++ /dev/null @@ -1,34 +0,0 @@ -# Task 21 — Landing Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `landing` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `landing/components/HeroSection.tsx` | ~3 | -| `landing/components/Features.tsx` | ~10 | -| `landing/components/HowItWorks.tsx` | ~5 | -| `landing/components/GetStarted.tsx` | ~5 | -| `landing/components/Navigation.tsx` | ~2 | -| `landing/components/FlowAnimation.tsx` | ~2 | -| `landing/components/Footer.tsx` | ~5 | - -## Strings a Traduzir (amostra) - -| String EN | String PT-BR | -|-----------|--------------| -| "All AI Providers" | "Todos os Provedores de IA" | -| "One Endpoint" | "Um Endpoint" | -| "Powerful Features" | "Recursos Poderosos" | -| "How OmniRoute Works" | "Como o OmniRoute Funciona" | -| "Install OmniRoute" | "Instalar o OmniRoute" | -| "Open Dashboard" | "Abrir Painel" | -| "Route Requests" | "Rotear Requisições" | -| "Data Location:" | "Local dos Dados:" | -| "Product" / "Resources" / "Legal" | "Produto" / "Recursos" / "Legal" | - -## Checklist -- [ ] Levantar strings completas de cada componente -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` e testar diff --git a/docs/i18n-tasks/22-docs.md b/docs/i18n-tasks/22-docs.md deleted file mode 100644 index 5c668173c2..0000000000 --- a/docs/i18n-tasks/22-docs.md +++ /dev/null @@ -1,32 +0,0 @@ -# Task 22 — Docs Page - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `docs` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `src/app/docs/page.tsx` | ~25 | - -## Strings a Traduzir - -| String EN | String PT-BR | -|-----------|--------------| -| "Quick Start" | "Início Rápido" | -| "Features" | "Recursos" | -| "Supported Providers" | "Provedores Suportados" | -| "Common Use Cases" | "Casos de Uso Comuns" | -| "Client Compatibility" | "Compatibilidade de Clientes" | -| "Cherry Studio" | "Cherry Studio" (não traduzir) | -| "Codex / GitHub Copilot Models" | "Modelos Codex / GitHub Copilot" | -| "Cursor IDE" | "Cursor IDE" (não traduzir) | -| "Claude Code / Antigravity" | "Claude Code / Antigravity" | -| "API Reference" | "Referência da API" | -| "Method" / "Path" / "Notes" | "Método" / "Caminho" / "Notas" | -| "Model Prefixes" | "Prefixos de Modelo" | -| "Prefix" / "Provider" / "Type" | "Prefixo" / "Provedor" / "Tipo" | -| "Troubleshooting" | "Solução de Problemas" | - -## Checklist -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` e testar diff --git a/docs/i18n-tasks/23-legal.md b/docs/i18n-tasks/23-legal.md deleted file mode 100644 index 8f98f362bc..0000000000 --- a/docs/i18n-tasks/23-legal.md +++ /dev/null @@ -1,31 +0,0 @@ -# Task 23 — Legal Pages (Privacy & Terms) - -**Status:** `[ ]` Não iniciado -**Namespace JSON:** `legal` - -## Arquivos -| Arquivo | Strings | -|---------|---------| -| `src/app/privacy/page.tsx` | ~10 | -| `src/app/terms/page.tsx` | ~5 | - -## Strings a Traduzir - -| String EN | String PT-BR | -|-----------|--------------| -| "Privacy Policy" | "Política de Privacidade" | -| "Terms of Service" | "Termos de Serviço" | -| "Provider configurations" | "Configurações de provedores" | -| "API keys" | "Chaves de API" | -| "Usage logs" | "Logs de uso" | -| "Application settings" | "Configurações do aplicativo" | -| "View and export usage analytics" | "Visualizar e exportar análises de uso" | -| "Clear usage history at any time" | "Limpar histórico de uso a qualquer momento" | -| "Configure log retention policies" | "Configurar políticas de retenção de logs" | -| "Back up and restore your database" | "Fazer backup e restaurar seu banco de dados" | - -## Checklist -- [ ] Adicionar chaves / traduções -- [ ] Substituir por `t()` e testar - -> **Nota:** Textos legais podem requerer revisão jurídica para tradução formal. diff --git a/docs/i18n-tasks/README.md b/docs/i18n-tasks/README.md deleted file mode 100644 index 67d3ec49c7..0000000000 --- a/docs/i18n-tasks/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# i18n Translation Tasks - -Cada arquivo `.md` nesta pasta representa **uma tarefa de tradução** para uma página ou componente do OmniRoute. - -## Status Legend - -- `[ ]` — Não iniciado -- `[/]` — Em progresso -- `[x]` — Concluído - -## Dashboard Pages (~260 strings) - -| # | Tarefa | Arquivo | Strings | Status | -| --- | ---------------------------------- | ----------------------------------------------------- | ------- | ------ | -| 01 | [Home](./01-home.md) | `HomePageClient.tsx` | ~25 | `[ ]` | -| 02 | [Analytics](./02-analytics.md) | `analytics/page.tsx` | ~8 | `[ ]` | -| 03 | [API Manager](./03-api-manager.md) | `api-manager/` | ~20 | `[ ]` | -| 04 | [Audit Log](./04-audit-log.md) | `audit-log/page.tsx`, `logs/AuditLogTab.tsx` | ~15 | `[ ]` | -| 05 | [CLI Tools](./05-cli-tools.md) | `cli-tools/components/*.tsx` | ~20 | `[ ]` | -| 06 | [Combos](./06-combos.md) | `combos/page.tsx` | ~20 | `[ ]` | -| 07 | [Costs](./07-costs.md) | `costs/page.tsx` | ~5 | `[ ]` | -| 08 | [Endpoint](./08-endpoint.md) | `endpoint/EndpointPageClient.tsx` | ~20 | `[ ]` | -| 09 | [Health](./09-health.md) | `health/page.tsx` | ~15 | `[ ]` | -| 10 | [Limits](./10-limits.md) | `limits/page.tsx` | ~5 | `[ ]` | -| 11 | [Logs](./11-logs.md) | `logs/` | ~5 | `[ ]` | -| 12 | [Onboarding](./12-onboarding.md) | `onboarding/page.tsx` | ~10 | `[ ]` | -| 13 | [Providers](./13-providers.md) | `providers/page.tsx`, `[id]/page.tsx`, `new/page.tsx` | ~20 | `[ ]` | -| 14 | [Settings](./14-settings.md) | `settings/components/*.tsx` | ~55 | `[ ]` | -| 15 | [Translator](./15-translator.md) | `translator/components/*.tsx` | ~25 | `[ ]` | -| 16 | [Usage](./16-usage.md) | `usage/components/*.tsx` | ~35 | `[ ]` | - -## Shared Components (~95 strings) - -| # | Tarefa | Arquivo(s) | Strings | Status | -| --- | ---------------------------------------------- | ---------------------------------------------------- | ------- | ------ | -| 17 | [Shared Modals](./17-shared-modals.md) | `OAuthModal`, `KiroAuthModal`, `PricingModal`, etc. | ~40 | `[ ]` | -| 18 | [Shared Loggers](./18-shared-loggers.md) | `RequestLoggerV2`, `ProxyLogger`, `ProxyLogDetail` | ~30 | `[ ]` | -| 19 | [Shared Charts & Stats](./19-shared-charts.md) | `UsageStats`, `analytics/charts`, `TokenHealthBadge` | ~25 | `[ ]` | - -## Non-Dashboard Pages (~75 strings) - -| # | Tarefa | Arquivo(s) | Strings | Status | -| --- | ---------------------------------- | ------------------------------------------------------- | ------- | ------ | -| 20 | [Login & Auth](./20-login-auth.md) | `login/`, `forgot-password/`, `callback/`, `forbidden/` | ~20 | `[ ]` | -| 21 | [Landing Page](./21-landing.md) | `landing/components/*.tsx` | ~25 | `[ ]` | -| 22 | [Docs Page](./22-docs.md) | `docs/page.tsx` | ~25 | `[ ]` | -| 23 | [Legal Pages](./23-legal.md) | `privacy/`, `terms/` | ~15 | `[ ]` | - ---- - -**Total estimado: ~460 strings em 23 tarefas** diff --git a/docs/i18n/ar/API_REFERENCE.md b/docs/i18n/ar/API_REFERENCE.md index 32a31f1068..b795722c11 100644 --- a/docs/i18n/ar/API_REFERENCE.md +++ b/docs/i18n/ar/API_REFERENCE.md @@ -1,12 +1,12 @@ -# مرجع واجهة برمجة التطبيقات +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -مرجع كامل لجميع نقاط نهاية OmniRoute API. +Complete reference for all OmniRoute API endpoints. --- -## جدول المحتويات +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## إكمالات الدردشة +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### رؤوس مخصصة +### Custom Headers -| رأس | الاتجاه | الوصف | -| ------------------------ | ------- | ------------------------------------------- | -| `X-OmniRoute-No-Cache` | طلب | اضبط على `true` لتجاوز ذاكرة التخزين المؤقت | -| `X-OmniRoute-Progress` | طلب | اضبط على `true` لأحداث التقدم | -| `Idempotency-Key` | طلب | مفتاح Dedup (نافذة 5 ثواني) | -| `X-Request-Id` | طلب | مفتاح إلغاء الحذف البديل | -| `X-OmniRoute-Cache` | الرد | `HIT` أو `MISS` (غير متدفق) | -| `X-OmniRoute-Idempotent` | الرد | `true` إذا تم إلغاء التكرار | -| `X-OmniRoute-Progress` | الرد | `enabled` إذا تم تتبع التقدم على | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## التضمينات +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -مقدمو الخدمة المتاحون: Nebius، وOpenAI، وMistral، وTogether AI، وFireworks، وNVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## توليد الصور +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -الموفرون المتاحون: OpenAI (DALL-E)، xAI (Grok Image)، Together AI (FLUX)، Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## قائمة النماذج +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## نقاط نهاية التوافق +## Compatibility Endpoints -| الطريقة | المسار | تنسيق | -| -------- | --------------------------- | --------------------- | -| مشاركة | `/v1/chat/completions` | أوبن آي | -| مشاركة | `/v1/messages` | انثروبي | -| مشاركة | `/v1/responses` | ردود OpenAI | -| مشاركة | `/v1/embeddings` | أوبن آي | -| مشاركة | `/v1/images/generations` | أوبن آي | -| احصل على | `/v1/models` | أوبن آي | -| مشاركة | `/v1/messages/count_tokens` | انثروبي | -| احصل على | `/v1beta/models` | الجوزاء | -| مشاركة | `/v1beta/models/{...path}` | الجوزاء توليد المحتوى | -| مشاركة | `/v1/api/chat` | أولاما | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### مسارات موفر مخصصة +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -تتم إضافة بادئة الموفر تلقائيًا في حالة فقدانها. تُرجع النماذج غير المتطابقة `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## ذاكرة التخزين المؤقت الدلالية +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -مثال الاستجابة: +Response example: ```json { @@ -162,154 +162,164 @@ DELETE /api/cache --- -## لوحة القيادة والإدارة +## Dashboard & Management -### المصادقة +### Authentication -| نقطة النهاية | الطريقة | الوصف | -| ----------------------------- | -------------- | ------------------------ | -| `/api/auth/login` | مشاركة | تسجيل الدخول | -| `/api/auth/logout` | مشاركة | تسجيل الخروج | -| `/api/settings/require-login` | الحصول على/وضع | تبديل تسجيل الدخول مطلوب | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### إدارة مقدمي الخدمة +### Provider Management -| نقطة النهاية | الطريقة | الوصف | -| ---------------------------- | ------------------ | --------------------------- | -| `/api/providers` | الحصول على/النشر | قائمة / إنشاء مقدمي الخدمات | -| `/api/providers/[id]` | الحصول على/وضع/حذف | إدارة مزود | -| `/api/providers/[id]/test` | مشاركة | اختبار اتصال الموفر | -| `/api/providers/[id]/models` | احصل على | قائمة نماذج المزود | -| `/api/providers/validate` | مشاركة | التحقق من صحة تكوين الموفر | -| `/api/provider-nodes*` | متنوع | إدارة عقدة الموفر | -| `/api/provider-models` | الحصول على/نشر/حذف | نماذج مخصصة | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### تدفقات OAuth +### OAuth Flows -| نقطة النهاية | الطريقة | الوصف | -| -------------------------------- | ------- | ------------------------ | -| `/api/oauth/[provider]/[action]` | متنوع | OAuth الخاص بموفر الخدمة | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### التوجيه والتكوين +### Routing & Config -| نقطة النهاية | الطريقة | الوصف | -| --------------------- | ---------------- | --------------------------------- | -| `/api/models/alias` | الحصول على/النشر | الأسماء المستعارة للنموذج | -| `/api/models/catalog` | احصل على | جميع الموديلات حسب المزود + النوع | -| `/api/combos*` | متنوع | إدارة التحرير والسرد | -| `/api/keys*` | متنوع | إدارة مفاتيح API | -| `/api/pricing` | احصل على | التسعير النموذجي | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### الاستخدام والتحليلات +### Usage & Analytics -| نقطة النهاية | الطريقة | الوصف | -| --------------------------- | -------- | --------------------- | -| `/api/usage/history` | احصل على | تاريخ الاستخدام | -| `/api/usage/logs` | احصل على | سجلات الاستخدام | -| `/api/usage/request-logs` | احصل على | سجلات على مستوى الطلب | -| `/api/usage/[connectionId]` | احصل على | الاستخدام لكل اتصال | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### الإعدادات +### Settings -| نقطة النهاية | الطريقة | الوصف | -| ------------------------------- | -------------- | ----------------------------------------------- | -| `/api/settings` | الحصول على/وضع | الإعدادات العامة | -| `/api/settings/proxy` | الحصول على/وضع | تكوين وكيل الشبكة | -| `/api/settings/proxy/test` | مشاركة | اختبار اتصال الوكيل | -| `/api/settings/ip-filter` | الحصول على/وضع | القائمة المسموح بها/القائمة المحظورة لعناوين IP | -| `/api/settings/thinking-budget` | الحصول على/وضع | الميزانية الرمزية المنطقية | -| `/api/settings/system-prompt` | الحصول على/وضع | موجه النظام العالمي | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### المراقبة +### Monitoring -| نقطة النهاية | الطريقة | الوصف | -| ------------------------ | -------------- | ----------------------------------- | -| `/api/sessions` | احصل على | تتبع الجلسة النشطة | -| `/api/rate-limits` | احصل على | حدود المعدل لكل حساب | -| `/api/monitoring/health` | احصل على | فحص الصحة | -| `/api/cache` | الحصول على/حذف | إحصائيات ذاكرة التخزين المؤقت / مسح | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### النسخ الاحتياطي والتصدير/الاستيراد +### Backup & Export/Import -| نقطة النهاية | الطريقة | الوصف | -| --------------------------- | -------- | -------------------------------------------------- | -| `/api/db-backups` | احصل على | قائمة النسخ الاحتياطية المتاحة | -| `/api/db-backups` | ضع | إنشاء نسخة احتياطية يدوية | -| `/api/db-backups` | مشاركة | استعادة من نسخة احتياطية محددة | -| `/api/db-backups/export` | احصل على | تنزيل قاعدة البيانات كملف .sqlite | -| `/api/db-backups/import` | مشاركة | قم بتحميل ملف .sqlite لاستبدال قاعدة البيانات | -| `/api/db-backups/exportAll` | احصل على | قم بتنزيل النسخة الاحتياطية الكاملة كأرشيف .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### المزامنة السحابية +### Cloud Sync -| نقطة النهاية | الطريقة | الوصف | -| ---------------------- | ------- | ------------------------ | -| `/api/sync/cloud` | متنوع | عمليات المزامنة السحابية | -| `/api/sync/initialize` | مشاركة | تهيئة المزامنة | -| `/api/cloud/*` | متنوع | إدارة السحابة | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### أدوات سطر الأوامر +### CLI Tools -| نقطة النهاية | الطريقة | الوصف | -| ---------------------------------- | -------- | ------------------- | -| `/api/cli-tools/claude-settings` | احصل على | حالة كلود CLI | -| `/api/cli-tools/codex-settings` | احصل على | حالة Codex CLI | -| `/api/cli-tools/droid-settings` | احصل على | حالة Droid CLI | -| `/api/cli-tools/openclaw-settings` | احصل على | حالة OpenClaw CLI | -| `/api/cli-tools/runtime/[toolId]` | احصل على | وقت تشغيل CLI العام | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -تتضمن استجابات واجهة سطر الأوامر: `installed`، `runnable`، `command`، `commandPath`، `runtimeMode`، `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### المرونة وحدود الأسعار +### ACP Agents -| نقطة النهاية | الطريقة | الوصف | -| ----------------------- | -------------- | ------------------------------------ | -| `/api/resilience` | الحصول على/وضع | الحصول على/تحديث ملفات تعريف المرونة | -| `/api/resilience/reset` | مشاركة | إعادة ضبط قواطع الدائرة | -| `/api/rate-limits` | احصل على | حالة حد المعدل لكل حساب | -| `/api/rate-limit` | احصل على | تكوين حد المعدل العالمي | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### التقييم +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| نقطة النهاية | الطريقة | الوصف | -| ------------ | ---------------- | ------------------------------------- | -| `/api/evals` | الحصول على/النشر | قائمة مجموعات التقييم / تشغيل التقييم | +### Resilience & Rate Limits -### السياسات +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| نقطة النهاية | الطريقة | الوصف | -| --------------- | ------------------ | -------------------- | -| `/api/policies` | الحصول على/نشر/حذف | إدارة سياسات التوجيه | +### Evals -###الامتثال +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| نقطة النهاية | الطريقة | الوصف | -| --------------------------- | -------- | ---------------------------- | -| `/api/compliance/audit-log` | احصل على | سجل تدقيق الامتثال (آخر رقم) | +### Policies -### v1beta (متوافق مع الجوزاء) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| نقطة النهاية | الطريقة | الوصف | -| -------------------------- | -------- | -------------------------------------- | -| `/v1beta/models` | احصل على | قائمة النماذج بصيغة الجوزاء | -| `/v1beta/models/{...path}` | مشاركة | الجوزاء `generateContent` نقطة النهاية | +### Compliance -تعكس نقاط النهاية هذه تنسيق Gemini API للعملاء الذين يتوقعون توافق Gemini SDK الأصلي. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### واجهات برمجة التطبيقات الداخلية / النظام +### v1beta (Gemini-Compatible) -| نقطة النهاية | الطريقة | الوصف | -| --------------- | -------- | -------------------------------------------------- | -| `/api/init` | احصل على | فحص تهيئة التطبيق (يستخدم عند التشغيل لأول مرة) | -| `/api/tags` | احصل على | علامات النماذج المتوافقة مع Ollama (لعملاء Ollama) | -| `/api/restart` | مشاركة | تشغيل إعادة تشغيل الخادم الرشيقة | -| `/api/shutdown` | مشاركة | تشغيل إيقاف تشغيل الخادم بشكل رشيق | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **ملاحظة:** يتم استخدام نقاط النهاية هذه داخليًا بواسطة النظام أو للتوافق مع عميل Ollama. لا يتم استدعاؤها عادة من قبل المستخدمين النهائيين. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## النسخ الصوتي +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -قم بنسخ الملفات الصوتية باستخدام Deepgram أو AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**الطلب:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**الرد:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**الموفرون المدعمون:** `deepgram/nova-3`، `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**التنسيقات المدعومة:** `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## التوافق مع أولاما +## Ollama Compatibility -بالنسبة للعملاء الذين يستخدمون تنسيق واجهة برمجة تطبيقات Olma: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -تتم ترجمة الطلبات تلقائيًا بين تنسيقات Ollama والتنسيقات الداخلية. +Requests are automatically translated between Ollama and internal formats. --- -## القياس عن بعد +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**الرد:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## الميزانية +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## توفر النموذج +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## معالجة الطلب +## Request Processing -1. يرسل العميل طلبًا إلى `/v1/*` -2. يستدعي معالج المسار `handleChat`، `handleEmbedding`، `handleAudioTranscription`، أو `handleImageGeneration` -3. تم حل النموذج (المزود/النموذج المباشر أو الاسم المستعار/السرد) -4. تم تحديد بيانات الاعتماد من قاعدة البيانات المحلية مع تصفية توفر الحساب -5. للدردشة: `handleChatCore` — اكتشاف التنسيق، والترجمة، والتحقق من ذاكرة التخزين المؤقت، والتحقق من عدم الكفاءة -6. يقوم منفذ الموفر بإرسال طلب المنبع -7. تتم ترجمة الاستجابة مرة أخرى إلى تنسيق العميل (الدردشة) أو إعادتها كما هي (التضمينات/الصور/الصوت) -8. تم تسجيل الاستخدام/التسجيل -9. يتم تطبيق الإجراء الاحتياطي على الأخطاء وفقًا لقواعد التحرير والسرد +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -مرجع البنية الكاملة: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## المصادقة +## Authentication -- تستخدم مسارات لوحة المعلومات (`/dashboard/*`) ملف تعريف الارتباط `auth_token` -- يستخدم تسجيل الدخول تجزئة كلمة المرور المحفوظة؛ الرجوع إلى `INITIAL_PASSWORD` -- `requireLogin` قابل للتبديل عبر `/api/settings/require-login` -- تتطلب مسارات `/v1/*` بشكل اختياري مفتاح Bearer API عندما `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/ar/ARCHITECTURE.md b/docs/i18n/ar/ARCHITECTURE.md index b004a627b0..258d62df53 100644 --- a/docs/i18n/ar/ARCHITECTURE.md +++ b/docs/i18n/ar/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# العمارة OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_آخر تحديث: 2026-02-18_ +_Last updated: 2026-03-04_ -## ملخص تنفيذي +## Executive Summary -OmniRoute عبارة عن بوابة توجيه محلية تعمل بالذكاء الاصطناعي ولوحة معلومات مبنية على Next.js. -فهو يوفر نقطة نهاية واحدة متوافقة مع OpenAI (`/v1/*`) ويوجه حركة المرور عبر العديد من موفري الخدمات الأولية مع الترجمة والاحتياط وتحديث الرمز المميز وتتبع الاستخدام. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -القدرات الأساسية: +Core capabilities: -- سطح API متوافق مع OpenAI لـ CLI/الأدوات (28 مزودًا) -- ترجمة الطلب/الاستجابة عبر تنسيقات الموفر -- نموذج احتياطي التحرير والسرد (تسلسل متعدد النماذج) -- احتياطي على مستوى الحساب (حسابات متعددة لكل مزود) -- إدارة اتصال موفر OAuth + API-key -- إنشاء التضمين عبر `/v1/embeddings` (6 موفري خدمات، 9 نماذج) -- إنشاء الصور عبر `/v1/images/generations` (4 مقدمي خدمات، 9 نماذج) -- فكر في تحليل العلامات (`...`) لنماذج الاستدلال -- تعقيم الاستجابة للتوافق الصارم مع OpenAI SDK -- تطبيع الدور (المطور → النظام، النظام → المستخدم) للتوافق بين الموفرين -- تحويل الإخراج المنظم (json_schema → Gemini ResponseSchema) -- الثبات المحلي لمقدمي الخدمات والمفاتيح والأسماء المستعارة والمجموعات والإعدادات والتسعير -- تتبع الاستخدام/التكلفة وتسجيل الطلب -- مزامنة سحابية اختيارية لمزامنة الأجهزة/الحالة المتعددة -- القائمة المسموح بها/القائمة المحظورة لـ IP للتحكم في الوصول إلى واجهة برمجة التطبيقات -- التفكير في إدارة الميزانية (العبور / التلقائي / المخصص / التكيفي) -- الحقن الفوري للنظام العالمي -- تتبع الجلسة وأخذ البصمات -- تحديد المعدل المحسن لكل حساب مع الملفات الشخصية الخاصة بالمزود -- نمط قاطع الدائرة لمرونة المزود -- حماية القطيع ضد الرعد مع قفل Mutex -- ذاكرة التخزين المؤقت لإلغاء البيانات المكررة للطلب المستندة إلى التوقيع -- طبقة المجال: توفر النموذج، وقواعد التكلفة، والسياسة الاحتياطية، وسياسة الإغلاق -- استمرارية حالة المجال (ذاكرة التخزين المؤقت للكتابة في SQLite للاحتياطيات والميزانيات وعمليات الإغلاق وقواطع الدائرة) -- محرك السياسة لتقييم الطلب المركزي (التأمين → الميزانية → الاحتياطي) -- طلب القياس عن بعد مع تجميع الكمون p50/p95/p99 -- معرف الارتباط (X-Request-Id) للتتبع الشامل -- تسجيل تدقيق الامتثال مع إلغاء الاشتراك لكل مفتاح API -- إطار تقييمي لضمان جودة LLM -- لوحة تحكم واجهة المستخدم المرنة مع حالة قاطع الدائرة في الوقت الفعلي -- موفرو OAuth المعياريون (12 وحدة فردية ضمن `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -نموذج وقت التشغيل الأساسي: +Primary runtime model: -- تقوم مسارات تطبيق Next.js ضمن `src/app/api/*` بتنفيذ كل من واجهات برمجة تطبيقات لوحة المعلومات وواجهات برمجة تطبيقات التوافق -- نواة توجيه/SSE مشتركة في `src/sse/*` + `open-sse/*` تتعامل مع تنفيذ الموفر والترجمة والتدفق والرجوع والاستخدام +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## النطاق والحدود +## Scope and Boundaries -### في النطاق +### In Scope -- وقت تشغيل البوابة المحلية -- واجهات برمجة التطبيقات لإدارة لوحة المعلومات -- مصادقة الموفر وتحديث الرمز المميز -- طلب الترجمة وتدفق SSE -- الحالة المحلية + استمرارية الاستخدام -- تنسيق مزامنة سحابية اختيارية +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### خارج النطاق +### Out of Scope -- تنفيذ الخدمة السحابية خلف `NEXT_PUBLIC_CLOUD_URL` -- مزود مستوى جيش تحرير السودان/مستوى التحكم خارج العملية المحلية -- ثنائيات CLI الخارجية نفسها (Claude CLI، Codex CLI، وما إلى ذلك) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## سياق النظام عالي المستوى +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## مكونات وقت التشغيل الأساسية +## Core Runtime Components -## 1) واجهة برمجة التطبيقات وطبقة التوجيه (مسارات تطبيق Next.js) +## 1) API and Routing Layer (Next.js App Routes) -الدلائل الرئيسية: +Main directories: -- `src/app/api/v1/*` و`src/app/api/v1beta/*` لواجهات برمجة تطبيقات التوافق -- `src/app/api/*` لواجهات برمجة التطبيقات للإدارة/التكوين -- تتم إعادة الكتابة التالية في الخريطة `next.config.mjs` من `/v1/*` إلى `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -طرق التوافق الهامة: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — يتضمن نماذج مخصصة مع `custom: true` -- `src/app/api/v1/embeddings/route.ts` — إنشاء التضمين (6 موفري) -- `src/app/api/v1/images/generations/route.ts` — إنشاء الصور (أكثر من 4 موفري خدمة، بما في ذلك Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — دردشة مخصصة لكل مزود -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — عمليات التضمين المخصصة لكل مزود -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — صور مخصصة لكل مزود +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -مجالات الإدارة: +Management domains: -- المصادقة/الإعدادات: `src/app/api/auth/*`، `src/app/api/settings/*` -- مقدمو الخدمة/الاتصالات: `src/app/api/providers*` -- عقد الموفر: `src/app/api/provider-nodes*` -- النماذج المخصصة: `src/app/api/provider-models` (GET/POST/DELETE) -- كتالوج النماذج: `src/app/api/models/catalog` (GET) -- تكوين الوكيل: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- المفاتيح/الأسماء المستعارة/المجموعات/التسعير: `src/app/api/keys*`، `src/app/api/models/alias`، `src/app/api/combos*`، `src/app/api/pricing` -- الاستخدام: `src/app/api/usage/*` -- المزامنة/السحابة: `src/app/api/sync/*`، `src/app/api/cloud/*` -- مساعدي أدوات CLI: `src/app/api/cli-tools/*` -- مرشح IP: `src/app/api/settings/ip-filter` (GET/PUT) -- ميزانية التفكير: `src/app/api/settings/thinking-budget` (GET/PUT) -- موجه النظام: `src/app/api/settings/system-prompt` (GET/PUT) -- الجلسات: `src/app/api/sessions` (GET) -- حدود الأسعار: `src/app/api/rate-limits` (GET) -- المرونة: `src/app/api/resilience` (GET/PATCH) - ملفات تعريف الموفر، قاطع الدائرة، حالة حد المعدل -- إعادة ضبط المرونة: `src/app/api/resilience/reset` (POST) — إعادة ضبط الفواصل + فترات التهدئة -- إحصائيات ذاكرة التخزين المؤقت: `src/app/api/cache/stats` (الحصول على/الحذف) -- توفر النموذج: `src/app/api/models/availability` (GET/POST) -- القياس عن بعد: `src/app/api/telemetry/summary` (GET) -- الميزانية: `src/app/api/usage/budget` (GET/POST) -- السلاسل الاحتياطية: `src/app/api/fallback/chains` (GET/POST/DELETE) -- تدقيق الامتثال: `src/app/api/compliance/audit-log` (GET) -- التقييمات: `src/app/api/evals` (GET/POST)، `src/app/api/evals/[suiteId]` (GET) -- السياسات: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + جوهر الترجمة +## 2) SSE + Translation Core -وحدات التدفق الرئيسية: +Main flow modules: -- الإدخال: `src/sse/handlers/chat.ts` -- التنسيق الأساسي: `open-sse/handlers/chatCore.ts` -- محولات تنفيذ الموفر: `open-sse/executors/*` -- اكتشاف التنسيق/تكوين الموفر: `open-sse/services/provider.ts` -- تحليل/حل النموذج: `src/sse/services/model.ts`، `open-sse/services/model.ts` -- المنطق الاحتياطي للحساب: `open-sse/services/accountFallback.ts` -- سجل الترجمة: `open-sse/translator/index.ts` -- تحويلات الدفق: `open-sse/utils/stream.ts`، `open-sse/utils/streamHandler.ts` -- استخراج/تسوية الاستخدام: `open-sse/utils/usageTracking.ts` -- محلل العلامات: `open-sse/utils/thinkTagParser.ts` -- معالج التضمين: `open-sse/handlers/embeddings.ts` -- تسجيل موفر التضمين: `open-sse/config/embeddingRegistry.ts` -- معالج إنشاء الصور: `open-sse/handlers/imageGeneration.ts` -- سجل موفر الصور: `open-sse/config/imageRegistry.ts` -- تعقيم الاستجابة: `open-sse/handlers/responseSanitizer.ts` -- تطبيع الدور: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -الخدمات (منطق الأعمال): +Services (business logic): -- اختيار الحساب/تسجيل النقاط: `open-sse/services/accountSelector.ts` -- إدارة دورة حياة السياق: `open-sse/services/contextManager.ts` -- فرض عامل تصفية IP: `open-sse/services/ipFilter.ts` -- تتبع الجلسة: `open-sse/services/sessionManager.ts` -- طلب إلغاء البيانات المكررة: `open-sse/services/signatureCache.ts` -- الحقن الفوري للنظام: `open-sse/services/systemPrompt.ts` -- إدارة ميزانية التفكير: `open-sse/services/thinkingBudget.ts` -- توجيه نموذج حرف البدل: `open-sse/services/wildcardRouter.ts` -- إدارة حدود السعر: `open-sse/services/rateLimitManager.ts` -- قاطع الدائرة: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -وحدات طبقة المجال: +Domain layer modules: -- توفر النموذج: `src/lib/domain/modelAvailability.ts` -- قواعد/ميزانيات التكلفة: `src/lib/domain/costRules.ts` -- السياسة الاحتياطية: `src/lib/domain/fallbackPolicy.ts` -- محلل التحرير والسرد: `src/lib/domain/comboResolver.ts` -- سياسة التأمين: `src/lib/domain/lockoutPolicy.ts` -- محرك السياسة: `src/domain/policyEngine.ts` — الإغلاق المركزي ← الميزانية ← التقييم الاحتياطي -- كتالوج رموز الأخطاء: `src/lib/domain/errorCodes.ts` -- معرف الطلب: `src/lib/domain/requestId.ts` -- مهلة الجلب: `src/lib/domain/fetchTimeout.ts` -- طلب القياس عن بعد: `src/lib/domain/requestTelemetry.ts` -- الامتثال/التدقيق: `src/lib/domain/compliance/index.ts` -- عداء التقييم: `src/lib/domain/evalRunner.ts` -- استمرارية حالة المجال: `src/lib/db/domainState.ts` — SQLite CRUD للسلاسل الاحتياطية، والميزانيات، وتاريخ التكلفة، وحالة الإغلاق، وقواطع الدائرة +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -وحدات موفر OAuth (12 ملفًا فرديًا ضمن `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- فهرس التسجيل: `src/lib/oauth/providers/index.ts` -- مقدمو الخدمات الأفراد: `claude.ts`، `codex.ts`، `gemini.ts`، `antigravity.ts`، `iflow.ts`، `qwen.ts`، `kimi-coding.ts`، `github.ts`، `kiro.ts`، `cursor.ts`، `kilocode.ts`، `cline.ts` -- الغلاف الرقيق: `src/lib/oauth/providers.ts` — إعادة التصدير من الوحدات الفردية +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) طبقة الثبات +## 3) Persistence Layer -قاعدة بيانات الحالة الأساسية: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- الملف: `${DATA_DIR}/db.json` (أو `$XDG_CONFIG_HOME/omniroute/db.json` عند التعيين، وإلا `~/.omniroute/db.json`) -- الكيانات:providerConnections، وproviderNodes، وmodelAliases، والمجموعات، وapiKeys، والإعدادات، والتسعير، **customModels**، **proxyConfig**، **ipFilter**، **thinkingBudget**، **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -قاعدة بيانات الاستخدام: +Usage persistence: -- `src/lib/usageDb.ts` -- الملفات: `${DATA_DIR}/usage.json`، `${DATA_DIR}/log.txt`، `${DATA_DIR}/call_logs/` -- يتبع نفس سياسة الدليل الأساسي مثل `localDb` (`DATA_DIR`، ثم `XDG_CONFIG_HOME/omniroute` عند التعيين) -- مقسمة إلى وحدات فرعية مركزة: `migrations.ts`، `usageHistory.ts`، `costCalculator.ts`، `usageStats.ts`، `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -قاعدة بيانات حالة المجال (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — عمليات CRUD لحالة المجال -- الجداول (التي تم إنشاؤها في `src/lib/db/core.ts`): `domain_fallback_chains`، `domain_budgets`، `domain_cost_history`، `domain_lockout_state`، `domain_circuit_breakers` -- نمط ذاكرة التخزين المؤقت للكتابة: تعد الخرائط الموجودة في الذاكرة موثوقة في وقت التشغيل؛ تتم كتابة الطفرات بشكل متزامن إلى SQLite؛ تتم استعادة الحالة من قاعدة البيانات عند البداية الباردة +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) المصادقة + الأسطح الأمنية +## 4) Auth + Security Surfaces -- مصادقة ملف تعريف الارتباط للوحة المعلومات: `src/proxy.ts`، `src/app/api/auth/login/route.ts` -- إنشاء/التحقق من مفتاح واجهة برمجة التطبيقات: `src/shared/utils/apiKey.ts` -- استمرت أسرار الموفر في إدخالات `providerConnections` -- دعم الوكيل الصادر عبر `open-sse/utils/proxyFetch.ts` (env vars) و`open-sse/utils/networkProxy.ts` (قابل للتكوين لكل موفر أو عالمي) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) المزامنة السحابية +## 5) Cloud Sync -- الحرف الأول للمجدول: `src/lib/initCloudSync.ts`، `src/shared/services/initializeCloudSync.ts` -- المهمة الدورية: `src/shared/services/cloudSyncScheduler.ts` -- مسار التحكم: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## دورة حياة الطلب (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## التحرير والسرد + التدفق الاحتياطي للحساب +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -يتم اتخاذ القرارات الاحتياطية بواسطة `open-sse/services/accountFallback.ts` باستخدام رموز الحالة والاستدلال على رسائل الخطأ. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## دورة حياة OAuth Onboarding وتحديث الرمز المميز +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -يتم تنفيذ التحديث أثناء حركة المرور المباشرة داخل `open-sse/handlers/chatCore.ts` عبر المنفذ `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## دورة حياة المزامنة السحابية (تمكين / مزامنة / تعطيل) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -يتم تشغيل المزامنة الدورية بواسطة `CloudSyncScheduler` عند تمكين السحابة. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## نموذج البيانات وخريطة التخزين +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -ملفات التخزين المادية: +Physical storage files: -- الحالة الرئيسية: `${DATA_DIR}/db.json` (أو `$XDG_CONFIG_HOME/omniroute/db.json` عند التعيين، وإلا `~/.omniroute/db.json`) -- إحصائيات الاستخدام: `${DATA_DIR}/usage.json` -- خطوط سجل الطلب: `${DATA_DIR}/log.txt` -- جلسات تصحيح أخطاء المترجم/الطلب الاختيارية: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## طبولوجيا النشر +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## تعيين الوحدة (القرار الحاسم) +## Module Mapping (Decision-Critical) -### وحدات المسار وواجهة برمجة التطبيقات +### Route and API Modules -- `src/app/api/v1/*`، `src/app/api/v1beta/*`: واجهات برمجة تطبيقات التوافق -- `src/app/api/v1/providers/[provider]/*`: مسارات مخصصة لكل مزود (الدردشة والتضمين والصور) -- `src/app/api/providers*`: موفر CRUD والتحقق من الصحة والاختبار -- `src/app/api/provider-nodes*`: إدارة العقدة المتوافقة المخصصة -- `src/app/api/provider-models`: إدارة النماذج المخصصة (CRUD) -- `src/app/api/models/catalog`: واجهة برمجة تطبيقات كتالوج النموذج الكامل (جميع الأنواع مجمعة حسب الموفر) -- `src/app/api/oauth/*`: تدفقات OAuth/رمز الجهاز -- `src/app/api/keys*`: دورة حياة مفتاح واجهة برمجة التطبيقات المحلية -- `src/app/api/models/alias`: إدارة الاسم المستعار -- `src/app/api/combos*`: إدارة التحرير والسرد الاحتياطية -- `src/app/api/pricing`: تجاوزات التسعير لحساب التكلفة -- `src/app/api/settings/proxy`: تكوين الوكيل (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: اختبار اتصال الوكيل الصادر (POST) -- `src/app/api/usage/*`: واجهات برمجة تطبيقات الاستخدام والسجلات -- `src/app/api/sync/*` + `src/app/api/cloud/*`: المزامنة السحابية والمساعدون الذين يواجهون السحابة -- `src/app/api/cli-tools/*`: كاتب/أداة فحص تكوين CLI المحلية -- `src/app/api/settings/ip-filter`: قائمة IP المسموح بها/القائمة المحظورة (GET/PUT) -- `src/app/api/settings/thinking-budget`: تكوين ميزانية الرمز المميز (GET/PUT) -- `src/app/api/settings/system-prompt`: موجه النظام العالمي (GET/PUT) -- `src/app/api/sessions`: قائمة الجلسة النشطة (GET) -- `src/app/api/rate-limits`: حالة حد السعر لكل حساب (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### التوجيه والتنفيذ الأساسي +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: تحليل الطلب، ومعالجة التحرير والسرد، وحلقة اختيار الحساب -- `open-sse/handlers/chatCore.ts`: الترجمة، إرسال المنفذ، معالجة إعادة المحاولة/التحديث، إعداد الدفق -- `open-sse/executors/*`: سلوك الشبكة والتنسيق الخاص بالموفر +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### سجل الترجمة ومحولات التنسيق +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: تسجيل المترجم وتنسيقه -- طلب المترجمين: `open-sse/translator/request/*` -- مترجمو الرد: `open-sse/translator/response/*` -- ثوابت التنسيق: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### المثابرة +### Persistence -- `src/lib/localDb.ts`: التكوين/الحالة المستمرة -- `src/lib/usageDb.ts`: سجل الاستخدام وسجلات الطلبات المتجددة +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## تغطية منفذي الخدمة (نمط الإستراتيجية) +## Provider Executor Coverage (Strategy Pattern) -كل مزود لديه منفذ متخصص يمتد `BaseExecutor` (في `open-sse/executors/base.ts`)، والذي يوفر بناء عنوان URL، وإنشاء الرأس، وإعادة المحاولة مع التراجع الأسي، وخطافات تحديث بيانات الاعتماد، وطريقة التنسيق `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| المنفذ | المزود (المقدمون) | التعامل الخاص | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI، Claude، Gemini، Qwen، iFlow، OpenRouter، GLM، Kimi، MiniMax، DeepSeek، Groq، xAI، Mistral، Perplexity، Together، Fireworks، Cerebras، Cohere، NVIDIA | تكوين عنوان URL/الرأس الديناميكي لكل مزود | -| `AntigravityExecutor` | جوجل مكافحة الجاذبية | معرفات المشروع/الجلسة المخصصة، إعادة المحاولة بعد التحليل | -| `CodexExecutor` | OpenAI Codex | يحقن تعليمات النظام، ويفرض جهدًا منطقيًا | -| `CursorExecutor` | بيئة تطوير متكاملة للمؤشر | بروتوكول ConnectRPC، تشفير Protobuf، طلب التوقيع عبر المجموع الاختباري | -| `GithubExecutor` | جيثب مساعد الطيار | تحديث الرمز المميز لـ Copilot، ورؤوس محاكاة VSCode | -| `KiroExecutor` | AWS CodeWhisperer/كيرو | تنسيق AWS EventStream الثنائي → تحويل SSE | -| `GeminiCLIExecutor` | الجوزاء CLI | دورة تحديث رمز OAuth المميز لـ Google | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -يستخدم جميع الموفرين الآخرين (بما في ذلك العقد المتوافقة المخصصة) `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## مصفوفة توافق الموفر +## Provider Compatibility Matrix -| مقدم | تنسيق | مصادقة | تيار | غير دفق | تحديث الرمز المميز | واجهة برمجة تطبيقات الاستخدام | -| ----------------------------------- | ---------------- | --------------------------- | --------------- | ------- | ------------------ | ----------------------------- | -| كلود | كلود | مفتاح API / OAuth | ✅ | ✅ | ✅ | ⚠️ المشرف فقط | -| الجوزاء | الجوزاء | مفتاح API / OAuth | ✅ | ✅ | ✅ | ⚠️ وحدة التحكم السحابية | -| الجوزاء CLI | الجوزاء-cli | أووث | ✅ | ✅ | ✅ | ⚠️ وحدة التحكم السحابية | -| مكافحة الجاذبية | ضد الجاذبية | أووث | ✅ | ✅ | ✅ | ✅ الحصة الكاملة API | -| أوبن آي | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| الدستور الغذائي | openai-responses | أووث | ✅ مجبور | ❌ | ✅ | ✅ حدود المعدل | -| جيثب مساعد الطيار | أوبيناي | OAuth + رمز مساعد الطيار | ✅ | ✅ | ✅ | ✅ لقطات الحصص | -| المؤشر | المؤشر | المجموع الاختباري المخصص | ✅ | ✅ | ❌ | ❌ | -| كيرو | كيرو | AWS SSO OIDC | ✅(ايفنت ستريم) | ❌ | ✅ | ✅ حدود الاستخدام | -| كوين | أوبيناي | أووث | ✅ | ✅ | ✅ | ⚠️ حسب الطلب | -| اي فلو | أوبيناي | OAuth (أساسي) | ✅ | ✅ | ✅ | ⚠️ حسب الطلب | -| اوبن راوتر | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| جي إل إم/كيمي/ميني ماكس | كلود | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| ديب سيك | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| جروك | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| xAI (جروك) | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| ميسترال | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| الحيرة | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| معا منظمة العفو الدولية | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| الألعاب النارية منظمة العفو الدولية | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| المخيخ | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| كوهير | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | -| نفيديا نيم | أوبيناي | مفتاح واجهة برمجة التطبيقات | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## تنسيق تغطية الترجمة +## Format Translation Coverage -تتضمن تنسيقات المصدر المكتشفة ما يلي: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -تتضمن التنسيقات المستهدفة ما يلي: +Target formats include: -- دردشة/ردود OpenAI -- كلود -- الجوزاء/الجوزاء-CLI/الظرف المضاد للجاذبية -- كيرو -- المؤشر +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -تستخدم الترجمات **OpenAI كتنسيق مركزي** — تمر جميع التحويلات عبر OpenAI كتنسيق وسيط: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -يتم تحديد الترجمات ديناميكيًا استنادًا إلى شكل حمولة المصدر والتنسيق المستهدف للموفر. +Translations are selected dynamically based on source payload shape and provider target format. -طبقات معالجة إضافية في مسار الترجمة: +Additional processing layers in the translation pipeline: -- **تطهير الاستجابة** — يزيل الحقول غير القياسية من استجابات تنسيق OpenAI (سواء المتدفقة أو غير المتدفقة) لضمان الامتثال الصارم لـ SDK -- **تطبيع الدور** — تحويل `developer` → `system` للأهداف غير التابعة لـ OpenAI؛ يدمج `system` → `user` للنماذج التي ترفض دور النظام (GLM، ERNIE) -- **فكر في استخراج العلامات** — يوزع كتل `...` من المحتوى إلى حقل `reasoning_content` -- **الإخراج المنظم** — يحول OpenAI `response_format.json_schema` إلى `responseMimeType` + `responseSchema` الخاص بـ Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## نقاط نهاية واجهة برمجة التطبيقات المدعومة +## Supported API Endpoints -| نقطة النهاية | تنسيق | معالج | -| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------------- | -| `POST /v1/chat/completions` | دردشة OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | رسائل كلود | نفس المعالج (تم اكتشافه تلقائيًا) | -| `POST /v1/responses` | ردود OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | تضمينات OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | قائمة النماذج | طريق API | -| `POST /v1/images/generations` | صور OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | قائمة النماذج | طريق API | -| `POST /v1/providers/{provider}/chat/completions` | دردشة OpenAI | مخصص لكل مزود مع التحقق من صحة النموذج | -| `POST /v1/providers/{provider}/embeddings` | تضمينات OpenAI | مخصص لكل مزود مع التحقق من صحة النموذج | -| `POST /v1/providers/{provider}/images/generations` | صور OpenAI | مخصص لكل مزود مع التحقق من صحة النموذج | -| `POST /v1/messages/count_tokens` | عدد كلود توكن | طريق API | -| `GET /v1/models` | قائمة نماذج OpenAI | مسار واجهة برمجة التطبيقات (الدردشة + التضمين + الصورة + النماذج المخصصة) | -| `GET /api/models/catalog` | كتالوج | جميع النماذج مجمعة حسب الموفر + النوع | -| `POST /v1beta/models/*:streamGenerateContent` | مولود برج الجوزاء | طريق API | -| `GET/PUT/DELETE /api/settings/proxy` | تكوين الوكيل | تكوين وكيل الشبكة | -| `POST /api/settings/proxy/test` | اتصال الوكيل | نقطة نهاية اختبار صحة الوكيل/الاتصال | -| `GET/POST/DELETE /api/provider-models` | نماذج مخصصة | إدارة النماذج المخصصة لكل مزود | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## تجاوز المعالج +## Bypass Handler -يعترض معالج التجاوز (`open-sse/utils/bypassHandler.ts`) طلبات "الرمي" المعروفة من Claude CLI - أصوات التمهيد، واستخراج العناوين، وعدد الرموز المميزة - ويعيد **استجابة زائفة** دون استهلاك الرموز المميزة للموفر الرئيسي. يتم تشغيل هذا فقط عندما يحتوي `User-Agent` على `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## طلب خط أنابيب المسجل +## Request Logger Pipeline -يوفر مسجل الطلب (`open-sse/utils/requestLogger.ts`) مسارًا لتسجيل تصحيح الأخطاء مكون من 7 مراحل، معطل افتراضيًا، وممكن عبر `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -تتم كتابة الملفات إلى `/logs//` لكل جلسة طلب. +Files are written to `/logs//` for each request session. -## أوضاع الفشل والمرونة +## Failure Modes and Resilience -## 1) توفر الحساب/المزود +## 1) Account/Provider Availability -- فترة تباطؤ حساب الموفر عند حدوث أخطاء عابرة/معدل/مصادقة -- احتياطي الحساب قبل فشل الطلب -- نموذج التحرير والسرد الاحتياطي عند استنفاد مسار النموذج/المزود الحالي +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) انتهاء صلاحية الرمز المميز +## 2) Token Expiry -- الفحص المسبق والتحديث مع إعادة المحاولة لموفري الخدمة القابلين للتحديث -- 401/403 إعادة المحاولة بعد محاولة التحديث في المسار الأساسي +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) سلامة الدفق +## 3) Stream Safety -- وحدة تحكم تيار قطع الاتصال -- دفق الترجمة مع تدفق نهاية الدفق ومعالجة `[DONE]` -- احتياطي تقدير الاستخدام عندما تكون البيانات الوصفية لاستخدام الموفر مفقودة +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) تدهور المزامنة السحابية +## 4) Cloud Sync Degradation -- ظهرت أخطاء المزامنة ولكن يستمر وقت التشغيل المحلي -- يحتوي المجدول على منطق قادر على إعادة المحاولة، ولكن التنفيذ الدوري يستدعي حاليًا مزامنة المحاولة الواحدة بشكل افتراضي +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) سلامة البيانات +## 5) Data Integrity -- ترحيل/إصلاح شكل قاعدة البيانات للمفاتيح المفقودة -- ضمانات إعادة تعيين JSON الفاسدة لـ localDb وuseDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## إمكانية الملاحظة والإشارات التشغيلية +## Observability and Operational Signals -مصادر رؤية وقت التشغيل: +Runtime visibility sources: -- سجلات وحدة التحكم من `src/sse/utils/logger.ts` -- مجاميع الاستخدام لكل طلب في `usage.json` -- سجل حالة الطلب النصي في `log.txt` -- سجلات الطلب/الترجمة العميقة الاختيارية ضمن `logs/` عندما `ENABLE_REQUEST_LOGS=true` -- نقاط نهاية استخدام لوحة المعلومات (`/api/usage/*`) لاستهلاك واجهة المستخدم +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## الحدود الحساسة للأمن +## Security-Sensitive Boundaries -- سر JWT (`JWT_SECRET`) يؤمن التحقق/التوقيع على ملف تعريف الارتباط لجلسة لوحة المعلومات -- يجب تجاوز الاحتياطي الأولي لكلمة المرور (`INITIAL_PASSWORD`، الافتراضي `123456`) في عمليات النشر الحقيقية -- سر HMAC لمفتاح API (`API_KEY_SECRET`) يؤمن تنسيق مفتاح API المحلي الذي تم إنشاؤه -- تظل أسرار الموفر (مفاتيح/رموز واجهة برمجة التطبيقات) موجودة في قاعدة البيانات المحلية ويجب حمايتها على مستوى نظام الملفات -- تعتمد نقاط نهاية المزامنة السحابية على مصادقة مفتاح API + دلالات معرف الجهاز +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## مصفوفة البيئة ووقت التشغيل +## Environment and Runtime Matrix -متغيرات البيئة المستخدمة بشكل نشط بواسطة التعليمات البرمجية: +Environment variables actively used by code: -- التطبيق/المصادقة: `JWT_SECRET`، `INITIAL_PASSWORD` -- التخزين: `DATA_DIR` -- سلوك العقدة المتوافقة: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- تجاوز قاعدة التخزين الاختيارية (Linux/macOS عند إلغاء تعيين `DATA_DIR`): `XDG_CONFIG_HOME` -- التجزئة الأمنية: `API_KEY_SECRET`، `MACHINE_ID_SALT` -- التسجيل: `ENABLE_REQUEST_LOGS` -- عنوان URL للمزامنة/السحابة: `NEXT_PUBLIC_BASE_URL`، `NEXT_PUBLIC_CLOUD_URL` -- الوكيل الصادر: `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY`، `NO_PROXY` ومتغيرات الأحرف الصغيرة -- علامات ميزات SOCKS5: `ENABLE_SOCKS5_PROXY`، `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- مساعدو النظام الأساسي/وقت التشغيل (ليس التكوين الخاص بالتطبيق): `APPDATA`، `NODE_ENV`، `PORT`، `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## الملاحظات المعمارية المعروفة +## Known Architectural Notes -1. يتشارك `usageDb` و`localDb` الآن نفس سياسة الدليل الأساسي (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) مع ترحيل الملفات القديمة. -2. يقوم `/api/v1/route.ts` بإرجاع قائمة نماذج ثابتة وهو ليس مصدر النماذج الرئيسي الذي يستخدمه `/v1/models`. -3. يقوم مسجل الطلب بكتابة الرؤوس/النص الكامل عند تمكينه؛ التعامل مع دليل السجل على أنه حساس. -4. يعتمد سلوك السحابة على `NEXT_PUBLIC_BASE_URL` الصحيح وإمكانية الوصول إلى نقطة نهاية السحابة. -5. تم نشر الدليل `open-sse/` باسم `@omniroute/open-sse` **حزمة مساحة عمل npm**. يقوم كود المصدر باستيراده عبر `@omniroute/open-sse/...` (تم حله بواسطة Next.js `transpilePackages`). لا تزال مسارات الملفات في هذا المستند تستخدم اسم الدليل `open-sse/` لتحقيق الاتساق. -6. تستخدم المخططات الموجودة في لوحة المعلومات **Recharts** (المستندة إلى SVG) لتصورات التحليلات التفاعلية التي يمكن الوصول إليها (المخططات الشريطية لاستخدام النموذج، والجداول التفصيلية للموفرين مع معدلات النجاح). -7. تستخدم اختبارات E2E **Playwright** (`tests/e2e/`)، ويتم تشغيلها عبر `npm run test:e2e`. تستخدم اختبارات الوحدة **مشغل اختبار Node.js** (`tests/unit/`)، ويتم تشغيله عبر `npm run test:plan3`. كود المصدر ضمن `src/` هو **TypeScript** (`.ts`/`.tsx`)؛ تظل مساحة العمل `open-sse/` JavaScript (`.js`). -8. تم تنظيم صفحة الإعدادات في 5 علامات تبويب: الأمان، التوجيه (6 إستراتيجيات عالمية: التعبئة أولاً، جولة روبن، p2c، عشوائي، الأقل استخدامًا، تحسين التكلفة)، المرونة (حدود المعدل القابلة للتحرير، قاطع الدائرة، السياسات)، الذكاء الاصطناعي (ميزانية التفكير، موجه النظام، ذاكرة التخزين المؤقت السريعة)، المتقدم (الوكيل). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## قائمة التحقق التشغيلية +## Operational Verification Checklist -- البناء من المصدر: `npm run build` -- إنشاء صورة Docker: `docker build -t omniroute .` -- ابدأ الخدمة وتحقق: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- يجب أن يكون عنوان URL الأساسي لهدف واجهة سطر الأوامر هو `http://:20128/v1` عندما يكون `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ar/CODEBASE_DOCUMENTATION.md b/docs/i18n/ar/CODEBASE_DOCUMENTATION.md index b6ce1bcee4..303880c198 100644 --- a/docs/i18n/ar/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/ar/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# الطريق الشامل - وثائق قاعدة التعليمات البرمجية +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> دليل شامل ومناسب للمبتدئين إلى جهاز التوجيه الوكيل AI **omniroute** متعدد الموفرين. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. ما هو الطريق الشامل؟ +## 1. What Is omniroute? -omniroute هو **جهاز توجيه وكيل** يقع بين عملاء الذكاء الاصطناعي (Claude CLI، وCodex، وCursor IDE، وما إلى ذلك) وموفري الذكاء الاصطناعي (Anthropic، وGoogle، وOpenAI، وAWS، وGitHub، وما إلى ذلك). إنه يحل مشكلة واحدة كبيرة: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **يتحدث عملاء الذكاء الاصطناعي المختلفون "لغات" مختلفة (تنسيقات واجهة برمجة التطبيقات)، ويتوقع مقدمو خدمات الذكاء الاصطناعي المختلفون "لغات" مختلفة أيضًا. ** يترجم المسار الشامل بينهم تلقائيًا. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -فكر في الأمر وكأنه مترجم عالمي في الأمم المتحدة - يمكن لأي مندوب التحدث بأي لغة، ويقوم المترجم بتحويلها لأي مندوب آخر. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. نظرة عامة على الهندسة المعمارية +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### المبدأ الأساسي: الترجمة المحورية +### Core Principle: Hub-and-Spoke Translation -تمر جميع ترجمة التنسيقات عبر **تنسيق OpenAI كمركز**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -هذا يعني أنك تحتاج فقط إلى مترجمين **N** (واحد لكل تنسيق) بدلاً من **N²** (كل زوج). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. هيكل المشروع +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. تفصيل الوحدة تلو الأخرى +## 4. Module-by-Module Breakdown -### 4.1 التكوين (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**المصدر الوحيد للحقيقة** لجميع إعدادات الموفر. +The **single source of truth** for all provider configuration. -| ملف | الغرض | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | كائن `PROVIDERS` يحتوي على عناوين URL الأساسية وبيانات اعتماد OAuth (الافتراضية) والرؤوس ومطالبات النظام الافتراضية لكل موفر. يحدد أيضًا `HTTP_STATUS`، و`ERROR_TYPES`، و`COOLDOWN_MS`، و`BACKOFF_CONFIG`، و`SKIP_PATTERNS`. | -| `credentialLoader.ts` | يقوم بتحميل بيانات الاعتماد الخارجية من `data/provider-credentials.json` ويدمجها في الإعدادات الافتراضية المشفرة في `PROVIDERS`. يحافظ على الأسرار خارج نطاق التحكم بالمصدر مع الحفاظ على التوافق مع الإصدارات السابقة. | -| `providerModels.ts` | سجل النموذج المركزي: الأسماء المستعارة لموفر الخرائط → معرفات النموذج. وظائف مثل `getModels()`، `getProviderByAlias()`. | -| `codexInstructions.ts` | تعليمات النظام التي تم إدخالها في طلبات الدستور الغذائي (قيود التحرير، قواعد الاختبار، سياسات الموافقة). | -| `defaultThinkingSignature.ts` | توقيعات "التفكير" الافتراضية لنماذج كلود وجيميني. | -| `ollamaModels.ts` | تعريف المخطط لنماذج أولاما المحلية (الاسم، الحجم، العائلة، التكميم). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### تدفق تحميل بيانات الاعتماد +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 المنفذون (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -يقوم المنفذون بتغليف **المنطق الخاص بالمزود** باستخدام **نمط الإستراتيجية**. يتجاوز كل منفذ الأساليب الأساسية حسب الحاجة. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| المنفذ | مقدم | التخصصات الرئيسية | -| ---------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | قاعدة الملخصات: إنشاء عنوان URL، والرؤوس، ومنطق إعادة المحاولة، وتحديث بيانات الاعتماد | -| `default.ts` | كلود، جيميني، أوبن آي آي، جي إل إم، كيمي، ميني ماكس | تحديث رمز OAuth العام للموفرين القياسيين | -| `antigravity.ts` | جوجل كلاود كود | إنشاء معرف المشروع/الجلسة، وإرجاع عناوين URL المتعددة، وإعادة محاولة التحليل المخصصة من رسائل الخطأ ("إعادة التعيين بعد 2 ساعة و7 دقائق و23 ثانية") | -| `cursor.ts` | بيئة تطوير متكاملة للمؤشر | **الأكثر تعقيدًا**: مصادقة المجموع الاختباري SHA-256، وترميز طلب Protobuf، وEventStream الثنائي → تحليل استجابة SSE | -| `codex.ts` | OpenAI Codex | إدخال تعليمات النظام، وإدارة مستويات التفكير، وإزالة المعلمات غير المدعومة | -| `gemini-cli.ts` | جوجل الجوزاء CLI | بناء عنوان URL المخصص (`streamGenerateContent`)، تحديث رمز OAuth المميز لـ Google | -| `github.ts` | جيثب مساعد الطيار | نظام الرمز المزدوج (GitHub OAuth + Copilot token)، محاكاة رأس VSCode | -| `kiro.ts` | AWS CodeWhisperer | التحليل الثنائي لـ AWS EventStream، وإطارات أحداث AMZN، وتقدير الرمز المميز | -| `index.ts` | — | المصنع: اسم موفر الخرائط ← فئة المنفذ، مع خيار احتياطي افتراضي | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 المعالجات (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**طبقة التنسيق** — تتولى تنسيق الترجمة والتنفيذ والتدفق ومعالجة الأخطاء. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| ملف | الغرض | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | ** المنسق المركزي ** (~ 600 سطر). يتعامل مع دورة حياة الطلب الكاملة: اكتشاف التنسيق ← الترجمة ← إرسال المنفذ ← استجابة التدفق/غير المتدفق ← تحديث الرمز المميز ← معالجة الأخطاء ← تسجيل الاستخدام. | -| `responsesHandler.ts` | محول واجهة برمجة تطبيقات استجابات OpenAI: يحول تنسيق الردود ← إكمالات الدردشة ← يرسل إلى `chatCore` ← يحول SSE مرة أخرى إلى تنسيق الردود. | -| `embeddings.ts` | معالج إنشاء التضمين: يحل نموذج التضمين → الموفر، ويرسل إلى واجهة برمجة تطبيقات الموفر، ويعيد استجابة التضمين المتوافقة مع OpenAI. يدعم 6+ مقدمي الخدمات. | -| `imageGeneration.ts` | معالج إنشاء الصور: يحل نموذج الصورة → الموفر، ويدعم الأوضاع المتوافقة مع OpenAI، وGemini-image (Antigravity)، والوضع الاحتياطي (Nebius). إرجاع صور base64 أو URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### دورة حياة الطلب (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 الخدمات (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -منطق الأعمال الذي يدعم المعالجات والمنفذين. +Business logic that supports the handlers and executors. -| ملف | الغرض | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **كشف التنسيق** (`detectFormat`): تحليلات بنية الجسم لتحديد تنسيقات Claude/OpenAI/Gemini/Antigravity/Responses (تتضمن `max_tokens` الاستدلال لكلود). أيضًا: بناء عنوان URL، وبناء الرأس، وتطبيع تكوين التفكير. يدعم موفري الخدمات الديناميكيين `openai-compatible-*` و`anthropic-compatible-*`. | -| `model.ts` | تحليل سلسلة النموذج (`claude/model-name` → `{provider: "claude", model: "model-name"}`)، ودقة الاسم المستعار مع اكتشاف التصادم، وتعقيم الإدخال (يرفض أحرف اجتياز المسار/التحكم)، ودقة معلومات النموذج مع دعم getter للاسم المستعار غير المتزامن. | -| `accountFallback.ts` | التعامل مع الحد الأقصى للمعدل: التراجع الأسي (1s → 2s → 4s → 2min كحد أقصى)، وإدارة فترة تهدئة الحساب، وتصنيف الأخطاء (أي الأخطاء تؤدي إلى التراجع مقابل عدم حدوثه). | -| `tokenRefresh.ts` | تحديث رمز OAuth المميز **لكل مزود**: Google (Gemini، Antigravity)، Claude، Codex، Qwen، iFlow، GitHub (OAuth + Copilot Dual-Token)، Kiro (AWS SSO OIDC + Social Auth). يتضمن ذاكرة تخزين مؤقت لإلغاء البيانات المكررة أثناء الرحلة وإعادة المحاولة مع التراجع المتسارع. | -| `combo.ts` | **نماذج مجمعة**: سلاسل من النماذج الاحتياطية. إذا فشل النموذج A مع وجود خطأ مؤهل للرجوع إليه، فجرّب النموذج B، ثم C، وما إلى ذلك. يقوم بإرجاع رموز الحالة الأولية الفعلية. | -| `usage.ts` | جلب بيانات الحصص/الاستخدام من واجهات برمجة تطبيقات الموفر (حصص GitHub Copilot، وحصص نماذج Antigravity، وحدود معدل Codex، وأعطال استخدام Kiro، وإعدادات Claude). | -| `accountSelector.ts` | اختيار الحساب الذكي باستخدام خوارزمية التسجيل: يأخذ في الاعتبار الأولوية والحالة الصحية والموضع الدائري وحالة التهدئة لاختيار الحساب الأمثل لكل طلب. | -| `contextManager.ts` | إدارة دورة حياة سياق الطلب: إنشاء وتتبع كائنات السياق لكل طلب باستخدام بيانات التعريف (معرف الطلب، والطوابع الزمنية، ومعلومات الموفر) لتصحيح الأخطاء والتسجيل. | -| `ipFilter.ts` | التحكم في الوصول المستند إلى IP: يدعم وضعي القائمة المسموح بها والقائمة المحظورة. التحقق من صحة عنوان IP للعميل مقابل القواعد التي تم تكوينها قبل معالجة طلبات واجهة برمجة التطبيقات. | -| `sessionManager.ts` | تتبع الجلسة باستخدام بصمة العميل: يتتبع الجلسات النشطة باستخدام معرفات العميل المجزأة، ويراقب عدد الطلبات، ويوفر مقاييس الجلسة. | -| `signatureCache.ts` | طلب ذاكرة التخزين المؤقت لإلغاء البيانات المكررة المستندة إلى التوقيع: يمنع الطلبات المكررة عن طريق تخزين توقيعات الطلب الأخيرة مؤقتًا وإرجاع الاستجابات المخزنة مؤقتًا للطلبات المتطابقة خلال نافذة زمنية. | -| `systemPrompt.ts` | الحقن الفوري للنظام العالمي: يُلحق أو يُلحق موجه نظام قابل للتكوين لجميع الطلبات، مع معالجة التوافق لكل مزود. | -| `thinkingBudget.ts` | إدارة ميزانية الرموز المميزة: تدعم أوضاع المرور، والتلقائي (تكوين التفكير الشريطي)، والمخصص (الميزانية الثابتة)، والتكيفية (مدرجة التعقيد) للتحكم في رموز التفكير/الاستدلال. | -| `wildcardRouter.ts` | توجيه نمط نموذج حرف البدل: يحل أنماط حرف البدل (على سبيل المثال، `*/claude-*`) لأزواج الموفر/النموذج الملموسة بناءً على التوفر والأولوية. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### إلغاء البيانات المكررة لتحديث الرمز المميز +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### آلة الحالة الاحتياطية للحساب +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### سلسلة نماذج كومبو +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### مترجم 4.5 (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**محرك ترجمة التنسيق** باستخدام نظام إضافي للتسجيل الذاتي. +The **format translation engine** using a self-registering plugin system. -####الهندسة المعمارية +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| الدليل | ملفات | الوصف | -| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 مترجمين | تحويل أجسام الطلب بين الصيغ. يتم تسجيل كل ملف ذاتيًا عبر `register(from, to, fn)` عند الاستيراد. | -| `response/` | 7 مترجمين | تحويل قطع الاستجابة المتدفقة بين الصيغ. يتعامل مع أنواع أحداث SSE وكتل التفكير واستدعاءات الأدوات. | -| `helpers/` | 6 مساعدين | الأدوات المساعدة المشتركة: `claudeHelper` (استخراج موجه النظام، تكوين التفكير)، `geminiHelper` (تعيين الأجزاء/المحتويات)، `openaiHelper` (تصفية التنسيق)، `toolCallHelper` (إنشاء المعرف، حقن الاستجابة المفقودة)، `maxTokensHelper`، `responsesApiHelper`. | -| `index.ts` | — | محرك الترجمة: `translateRequest()`، `translateResponse()`، إدارة الحالة، التسجيل. | -| `formats.ts` | — | ثوابت التنسيق: `OPENAI`، `CLAUDE`، `GEMINI`، `ANTIGRAVITY`، `KIRO`، `CURSOR`، `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### التصميم الرئيسي: المكونات الإضافية للتسجيل الذاتي +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 الأدوات المساعدة (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| ملف | الغرض | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | إنشاء استجابة للأخطاء (تنسيق متوافق مع OpenAI)، وتحليل الأخطاء الأولية، واستخراج وقت إعادة محاولة Antigravity من رسائل الخطأ، وتدفق أخطاء SSE. | -| `stream.ts` | **SSE Transform Stream** — خط أنابيب البث الأساسي. وضعان: `TRANSLATE` (ترجمة التنسيق الكامل) و`PASSTHROUGH` (تطبيع + استخراج الاستخدام). يتعامل مع التخزين المؤقت للقطعة وتقدير الاستخدام وتتبع طول المحتوى. تتجنب مثيلات وحدة التشفير/وحدة فك التشفير لكل تيار الحالة المشتركة. | -| `streamHelpers.ts` | أدوات SSE ذات المستوى المنخفض: `parseSSELine` (تتحمل المسافات البيضاء)، `hasValuableContent` (تصفية الأجزاء الفارغة لـ OpenAI/Claude/Gemini)، `fixInvalidId`، `formatSSE` (تسلسل SSE مدرك للتنسيق مع تنظيف `perf_metrics`). | -| `usageTracking.ts` | استخراج استخدام الرمز المميز من أي تنسيق (Claude/OpenAI/Gemini/Responses)، والتقدير باستخدام نسب الأحرف لكل رمز مميز للأداة/الرسالة، وإضافة المخزن المؤقت (هامش أمان 2000 رمز مميز)، وتصفية الحقول الخاصة بالتنسيق، وتسجيل وحدة التحكم بألوان ANSI. | -| `requestLogger.ts` | تسجيل الطلب المستند إلى الملف (الاشتراك عبر `ENABLE_REQUEST_LOGS=true`). ينشئ مجلدات الجلسة بملفات مرقمة: `1_req_client.json` → `7_res_client.txt`. كل عمليات الإدخال/الإخراج غير متزامنة (أطلق النار وانسى). أقنعة الرؤوس الحساسة. | -| `bypassHandler.ts` | يعترض أنماطًا محددة من Claude CLI (استخراج العنوان، والتحمية، والعد) ويعيد استجابات مزيفة دون الاتصال بأي مزود. يدعم كلا من الدفق وغير الدفق. يقتصر عمدا على نطاق كلود CLI. | -| `networkProxy.ts` | يحل عنوان URL للوكيل الصادر لموفر معين مع الأسبقية: التكوين الخاص بالموفر → التكوين العام → متغيرات البيئة (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). يدعم استثناءات `NO_PROXY`. تكوين ذاكرة التخزين المؤقت لمدة 30 ثانية. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### خط أنابيب تدفق SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### بنية جلسة مسجل الطلب +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 طبقة التطبيق (`src/`) +### 4.7 Application Layer (`src/`) -| الدليل | الغرض | -| ------------- | ------------------------------------------------------------------------------------------------------- | -| `src/app/` | واجهة مستخدم الويب، مسارات واجهة برمجة التطبيقات (API)، البرامج الوسيطة السريعة، معالجات رد اتصال OAuth | -| `src/lib/` | الوصول إلى قاعدة البيانات (`localDb.ts`، `usageDb.ts`)، المصادقة، مشتركة | -| `src/mitm/` | أدوات مساعدة للوكيل الوسيط لاعتراض حركة مرور الموفر | -| `src/models/` | تعريفات نماذج قواعد البيانات | -| `src/shared/` | أغلفة حول وظائف open-sse (المزود، الدفق، الخطأ، إلخ) | -| `src/sse/` | معالجات نقطة نهاية SSE التي تربط مكتبة open-sse بمسارات Express | -| `src/store/` | إدارة حالة التطبيق | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### مسارات API البارزة +#### Notable API Routes -| الطريق | طرق | الغرض | -| --------------------------------------------- | ------------------ | ------------------------------------------------------------------------------ | -| `/api/provider-models` | الحصول على/نشر/حذف | CRUD للنماذج المخصصة لكل مزود | -| `/api/models/catalog` | احصل على | كتالوج مجمع لجميع النماذج (الدردشة، التضمين، الصورة، المخصصة) مجمعة حسب الموفر | -| `/api/settings/proxy` | الحصول على/وضع/حذف | تكوين الوكيل الصادر الهرمي (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | مشاركة | التحقق من صحة اتصال الوكيل وإرجاع IP/زمن الوصول العام | -| `/v1/providers/[provider]/chat/completions` | مشاركة | عمليات إكمال الدردشة المخصصة لكل مزود مع التحقق من صحة النموذج | -| `/v1/providers/[provider]/embeddings` | مشاركة | عمليات التضمين المخصصة لكل مزود مع التحقق من صحة النموذج | -| `/v1/providers/[provider]/images/generations` | مشاركة | إنشاء صور مخصصة لكل مزود مع التحقق من صحة النموذج | -| `/api/settings/ip-filter` | الحصول على/وضع | قائمة IP المسموح بها/إدارة القائمة المحظورة | -| `/api/settings/thinking-budget` | الحصول على/وضع | تكوين ميزانية الرمز المميز (العبور/التلقائي/المخصص/التكيفي) | -| `/api/settings/system-prompt` | الحصول على/وضع | الحقن الفوري للنظام العالمي لجميع الطلبات | -| `/api/sessions` | احصل على | تتبع الجلسة النشطة ومقاييسها | -| `/api/rate-limits` | احصل على | حالة حد المعدل لكل حساب | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. أنماط التصميم الرئيسية +## 5. Key Design Patterns -### 5.1 الترجمة المحورية والمتحدثة +### 5.1 Hub-and-Spoke Translation -تتم ترجمة جميع التنسيقات من خلال **تنسيق OpenAI كمحور**. لا تتطلب إضافة موفر جديد سوى كتابة **زوج واحد** من المترجمين (من/إلى OpenAI)، وليس عدد N من المترجمين. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 نمط استراتيجية المنفذ +### 5.2 Executor Strategy Pattern -كل مزود لديه فئة منفذة مخصصة ترث من `BaseExecutor`. يقوم المصنع في `executors/index.ts` باختيار المصنع المناسب في وقت التشغيل. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 نظام البرنامج المساعد للتسجيل الذاتي +### 5.3 Self-Registering Plugin System -تسجل وحدات المترجم نفسها عند الاستيراد عبر `register()`. إن إضافة مترجم جديد يعني مجرد إنشاء ملف واستيراده. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 التراجع في الحساب مع التراجع الأسي +### 5.4 Account Fallback with Exponential Backoff -عندما يقوم مقدم الخدمة بإرجاع 429/401/500، يمكن للنظام التبديل إلى الحساب التالي، مع تطبيق فترات التباطؤ الأسية (1ث → 2ث → 4ث → 2 دقيقة كحد أقصى). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 سلاسل نماذج كومبو +### 5.5 Combo Model Chains -يقوم "التحرير والسرد" بتجميع سلاسل `provider/model` متعددة. إذا فشل الأول، يتم الرجوع إلى التالي تلقائيًا. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 ترجمة متدفقة رائعة +### 5.6 Stateful Streaming Translation -تحافظ ترجمة الاستجابة على الحالة عبر أجزاء SSE (تتبع كتلة التفكير، وتراكم استدعاءات الأداة، وفهرسة كتلة المحتوى) عبر آلية `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 المخزن المؤقت لسلامة الاستخدام +### 5.7 Usage Safety Buffer -تتم إضافة مخزن مؤقت مكون من 2000 رمز مميز إلى الاستخدام المبلغ عنه لمنع العملاء من الوصول إلى حدود نافذة السياق بسبب الحمل الزائد من مطالبات النظام وترجمة التنسيق. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. التنسيقات المدعومة +## 6. Supported Formats -| تنسيق | الاتجاه | المعرف | -| ----------------------------------- | -------------- | ------------------ | -| استكمالات الدردشة OpenAI | المصدر + الهدف | `openai` | -| واجهة برمجة تطبيقات استجابات OpenAI | المصدر + الهدف | `openai-responses` | -| أنثروبي كلود | المصدر + الهدف | `claude` | -| جوجل الجوزاء | المصدر + الهدف | `gemini` | -| جوجل الجوزاء CLI | الهدف فقط | `gemini-cli` | -| مكافحة الجاذبية | المصدر + الهدف | `antigravity` | -| أوس كيرو | الهدف فقط | `kiro` | -| المؤشر | الهدف فقط | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. مقدمو الخدمة المدعومين +## 7. Supported Providers -| مقدم | طريقة المصادقة | المنفذ | الملاحظات الرئيسية | -| ------------------------- | ------------------------ | --------------- | --------------------------------------------------------- | -| أنثروبي كلود | مفتاح API أو OAuth | الافتراضي | يستخدم رأس `x-api-key` | -| جوجل الجوزاء | مفتاح API أو OAuth | الافتراضي | يستخدم رأس `x-goog-api-key` | -| جوجل الجوزاء CLI | أووث | الجوزاء كلي | يستخدم `streamGenerateContent` نقطة النهاية | -| مكافحة الجاذبية | أووث | مكافحة الجاذبية | احتياطي عناوين URL المتعددة، إعادة محاولة التحليل المخصصة | -| أوبن آي | مفتاح API | الافتراضي | مصادقة حامل المعيار | -| الدستور الغذائي | أووث | الدستور الغذائي | يدخل تعليمات النظام ويدير التفكير | -| جيثب مساعد الطيار | OAuth + رمز مساعد الطيار | جيثب | رمز مزدوج، محاكاة رأس VSCode | -| كيرو (AWS) | AWS SSO OIDC أو Social | كيرو | تحليل دفق الأحداث الثنائية | -| بيئة تطوير متكاملة للمؤشر | مصادقة المجموع الاختباري | المؤشر | ترميز Protobuf، المجموع الاختباري SHA-256 | -| كوين | أووث | الافتراضي | المصادقة القياسية | -| اي فلو | OAuth (أساسي + حامل) | الافتراضي | رأس المصادقة المزدوجة | -| اوبن راوتر | مفتاح API | الافتراضي | مصادقة حامل المعيار | -| جي إل إم، كيمي، ميني ماكس | مفتاح API | الافتراضي | متوافق مع كلود، استخدم `x-api-key` | -| `openai-compatible-*` | مفتاح API | الافتراضي | ديناميكي: أي نقطة نهاية متوافقة مع OpenAI | -| `anthropic-compatible-*` | مفتاح API | الافتراضي | ديناميكي: أي نقطة نهاية متوافقة مع كلود | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. ملخص تدفق البيانات +## 8. Data Flow Summary -### طلب البث +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### طلب عدم البث +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### تجاوز التدفق (كلود CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/ar/FEATURES.md b/docs/i18n/ar/FEATURES.md index 00115fca20..82cc73b67b 100644 --- a/docs/i18n/ar/FEATURES.md +++ b/docs/i18n/ar/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — معرض ميزات لوحة المعلومات +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -دليل مرئي لكل قسم من لوحة معلومات OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 مقدمو الخدمة +## 🔌 Providers -إدارة اتصالات مزودي الذكاء الاصطناعي: موفري OAuth (Claude Code وCodex وGemini CLI) وموفري مفاتيح API (Groq وDeepSeek وOpenRouter) ومقدمي الخدمات المجانية (iFlow وQwen وKiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 المجموعات +## 🎨 Combos -أنشئ مجموعات توجيه النماذج باستخدام 6 إستراتيجيات: التعبئة أولاً، والتدوير الدائري، وقوة الاختيارين، والعشوائية، والأقل استخدامًا، والمُحسَّنة من حيث التكلفة. تقوم كل مجموعة بتسلسل نماذج متعددة مع الرجوع التلقائي. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊تحليلات +## 📊 Analytics -تحليلات استخدام شاملة مع استهلاك الرمز المميز، وتقديرات التكلفة، وخرائط النشاط، ومخططات التوزيع الأسبوعية، والتفاصيل لكل مزود. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 صحة النظام +## 🏥 System Health -المراقبة في الوقت الفعلي: وقت التشغيل، والذاكرة، والإصدار، والنسب المئوية لزمن الوصول (p50/p95/p99)، وإحصائيات ذاكرة التخزين المؤقت، وحالات قاطع دائرة الموفر. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 ملعب المترجم +## 🔧 Translator Playground -أربعة أوضاع لتصحيح أخطاء ترجمات واجهة برمجة التطبيقات: **ساحة اللعب** (محول التنسيق)، **اختبار الدردشة** (الطلبات المباشرة)، **منصة الاختبار** (اختبارات الدفعة)، و **المراقب المباشر** (البث في الوقت الفعلي). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ الإعدادات +## 🎮 Model Playground _(v2.0.9+)_ -الإعدادات العامة، وتخزين النظام، وإدارة النسخ الاحتياطي (قاعدة بيانات التصدير/الاستيراد)، والمظهر (الوضع الداكن/الفاتح)، والأمان (يتضمن حماية نقطة نهاية واجهة برمجة التطبيقات وحظر الموفر المخصص)، والتوجيه، والمرونة، والتكوين المتقدم. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 أدوات CLI +## 🔧 CLI Tools -تكوين بنقرة واحدة لأدوات ترميز الذكاء الاصطناعي: Claude Code، وCodex CLI، وGemini CLI، وOpenClaw، وKilo Code، وAntigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 سجلات الطلب +## 🤖 CLI Agents _(v2.0.11+)_ -تسجيل الطلبات في الوقت الفعلي مع التصفية حسب الموفر والطراز والحساب ومفتاح واجهة برمجة التطبيقات. يعرض رموز الحالة واستخدام الرمز المميز ووقت الاستجابة وتفاصيل الاستجابة. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 نقطة نهاية API +## 🌐 API Endpoint -نقطة نهاية واجهة برمجة التطبيقات الموحدة الخاصة بك مع تفاصيل الإمكانات: عمليات إكمال الدردشة والتضمين وإنشاء الصور وإعادة الترتيب والنسخ الصوتي ومفاتيح واجهة برمجة التطبيقات المسجلة. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ar/TROUBLESHOOTING.md b/docs/i18n/ar/TROUBLESHOOTING.md index 3a4cfd58fa..120092d63c 100644 --- a/docs/i18n/ar/TROUBLESHOOTING.md +++ b/docs/i18n/ar/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# استكشاف الأخطاء وإصلاحها +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -المشاكل والحلول الشائعة لـ OmniRoute. +Common problems and solutions for OmniRoute. --- -## إصلاحات سريعة +## Quick Fixes -| مشكلة | الحل | -| --------------------------------- | ----------------------------------------------------------------- | -| تسجيل الدخول الأول لا يعمل | تحقق من `INITIAL_PASSWORD` في `.env` (الافتراضي: `123456`) | -| تفتح لوحة المعلومات على منفذ خاطئ | اضبط `PORT=20128` و`NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| لا توجد سجلات للطلب ضمن `logs/` | تعيين `ENABLE_REQUEST_LOGS=true` | -| EACCES: تم رفض الإذن | اضبط `DATA_DIR=/path/to/writable/dir` لتجاوز `~/.omniroute` | -| استراتيجية التوجيه لا تنقذ | التحديث إلى الإصدار 1.4.11+ (إصلاح مخطط Zod لاستمرارية الإعدادات) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## مشكلات المزود +## Provider Issues -### "نموذج اللغة لم يقدم رسائل" +### "Language model did not provide messages" -**السبب:** استنفدت حصة الموفر. +**Cause:** Provider quota exhausted. -**الإصلاح:** +**Fix:** -1. تحقق من تعقب الحصص في لوحة القيادة -2. استخدم مجموعة من المستويات الاحتياطية -3. قم بالتبديل إلى الطبقة الأرخص/المجانية +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### تحديد المعدل +### Rate Limiting -**السبب:** استنفدت حصة الاشتراك. +**Cause:** Subscription quota exhausted. -**الإصلاح:** +**Fix:** -- إضافة احتياطي: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- استخدم GLM/MiniMax كنسخة احتياطية رخيصة الثمن +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### انتهت صلاحية رمز OAuth +### OAuth Token Expired -يقوم OmniRoute بتحديث الرموز المميزة تلقائيًا. إذا استمرت المشكلات: +OmniRoute auto-refreshes tokens. If issues persist: -1. لوحة المعلومات → الموفر → إعادة الاتصال -2. قم بحذف وإعادة إضافة اتصال الموفر +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## مشكلات السحابة +## Cloud Issues -### أخطاء المزامنة السحابية +### Cloud Sync Errors -1. تحقق من نقاط `BASE_URL` لمثيلك قيد التشغيل (على سبيل المثال، `http://localhost:20128`) -2. تحقق من نقاط `CLOUD_URL` إلى نقطة نهاية السحابة الخاصة بك (على سبيل المثال، `https://omniroute.dev`) -3. حافظ على محاذاة قيم `NEXT_PUBLIC_*` مع القيم من جانب الخادم +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### السحابة `stream=false` تُرجع 500 +### Cloud `stream=false` Returns 500 -**العَرَض:** `Unexpected token 'd'...` على نقطة نهاية السحابة للمكالمات غير المتدفقة. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**السبب:** يقوم المنبع بإرجاع حمولة SSE بينما يتوقع العميل JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**الحل البديل:** استخدم `stream=true` للمكالمات السحابية المباشرة. يتضمن وقت التشغيل المحلي SSE → JSON الاحتياطي. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### تقول السحابة إنها متصلة ولكن "مفتاح واجهة برمجة التطبيقات غير صالح" +### Cloud Says Connected but "Invalid API key" -1. قم بإنشاء مفتاح جديد من لوحة المعلومات المحلية (`/api/keys`) -2. قم بتشغيل المزامنة السحابية: قم بتمكين السحابة → المزامنة الآن -3. لا يزال بإمكان المفاتيح القديمة/غير المتزامنة إرجاع `401` على السحابة +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## مشكلات عامل الميناء +## Docker Issues -### تظهر أداة CLI غير مثبتة +### CLI Tool Shows Not Installed -1. تحقق من حقول وقت التشغيل: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. بالنسبة للوضع المحمول: استخدم هدف الصورة `runner-cli` (CLIs المجمعة) -3. بالنسبة لوضع تثبيت المضيف: قم بتعيين `CLI_EXTRA_PATHS` وتثبيت دليل حاوية المضيف للقراءة فقط -4. إذا تم العثور على `installed=true` و`runnable=false`: ثنائي ولكن فشل التحقق من الصحة +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### التحقق السريع من وقت التشغيل +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## قضايا التكلفة +## Cost Issues -### ارتفاع التكاليف +### High Costs -1. تحقق من إحصائيات الاستخدام في لوحة المعلومات → الاستخدام -2. قم بتبديل النموذج الأساسي إلى GLM/MiniMax -3. استخدم الطبقة المجانية (Gemini CLI، iFlow) للمهام غير الحرجة -4. قم بتعيين ميزانيات التكلفة لكل مفتاح واجهة برمجة التطبيقات: لوحة المعلومات ← مفاتيح واجهة برمجة التطبيقات ← الميزانية +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## التصحيح +## Debugging -### تمكين سجلات الطلبات +### Enable Request Logs -قم بتعيين `ENABLE_REQUEST_LOGS=true` في ملف `.env` الخاص بك. تظهر السجلات ضمن الدليل `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### التحقق من صحة مقدم الخدمة +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### تخزين وقت التشغيل +### Runtime Storage -- الحالة الرئيسية: `${DATA_DIR}/db.json` (المزودون، المجموعات، الأسماء المستعارة، المفاتيح، الإعدادات) -- الاستخدام: `${DATA_DIR}/usage.json`، `${DATA_DIR}/log.txt`، `${DATA_DIR}/call_logs/` -- سجلات الطلب: `/logs/...` (عندما `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## مشكلات قواطع الدائرة +## Circuit Breaker Issues -### الموفر عالق في الحالة المفتوحة +### Provider stuck in OPEN state -عندما يكون قاطع دائرة الموفر مفتوحًا، يتم حظر الطلبات حتى تنتهي فترة التهدئة. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**الإصلاح:** +**Fix:** -1. انتقل إلى **لوحة التحكم ← الإعدادات ← المرونة** -2. تحقق من بطاقة قاطع الدائرة الكهربائية الخاصة بالمزود المتأثر -3. انقر فوق **إعادة تعيين الكل** لمسح جميع القواطع، أو انتظر حتى تنتهي فترة التهدئة -4. تحقق من أن الموفر متاح فعليًا قبل إعادة التعيين +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### يستمر المزود في تعطيل قاطع الدائرة +### Provider keeps tripping the circuit breaker -إذا دخل مقدم الخدمة بشكل متكرر في الحالة المفتوحة: +If a provider repeatedly enters OPEN state: -1. تحقق من **Dashboard → Health → Provider Health** لمعرفة نمط الفشل -2. انتقل إلى **الإعدادات → المرونة → ملفات تعريف الموفر** وقم بزيادة حد الفشل -3. تحقق مما إذا كان الموفر قد قام بتغيير حدود واجهة برمجة التطبيقات (API) أو طلب إعادة المصادقة -4. قم بمراجعة القياس عن بعد لزمن الاستجابة - قد يتسبب زمن الاستجابة العالي في حدوث أعطال بسبب انتهاء المهلة +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## مشكلات النسخ الصوتي +## Audio Transcription Issues -### خطأ "نموذج غير مدعوم". +### "Unsupported model" error -- تأكد من أنك تستخدم البادئة الصحيحة: `deepgram/nova-3` أو `assemblyai/best` -- تحقق من أن الموفر متصل في **لوحة التحكم ← الموفرون** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### يعود النسخ فارغًا أو يفشل +### Transcription returns empty or fails -- تحقق من تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm` -- التحقق من أن حجم الملف يقع ضمن حدود الموفر (عادةً أقل من 25 ميجابايت) -- التحقق من صلاحية مفتاح API الخاص بالموفر في بطاقة المزود +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## تصحيح أخطاء المترجم +## Translator Debugging -استخدم **لوحة المعلومات → المترجم** لتصحيح مشكلات ترجمة التنسيق: +Use **Dashboard → Translator** to debug format translation issues: -| الوضع | متى تستخدم | -| -------------------- | ---------------------------------------------------------------------------------- | -| **ساحة اللعب** | قارن تنسيقات الإدخال/الإخراج جنبًا إلى جنب — الصق طلبًا فاشلاً لترى كيف تتم ترجمته | -| ** اختبار الدردشة ** | أرسل رسائل مباشرة وافحص حمولة الطلب/الاستجابة الكاملة بما في ذلك الرؤوس | -| ** مقعد الاختبار ** | قم بإجراء اختبارات مجمعة عبر مجموعات التنسيق للعثور على الترجمات المعطلة | -| **مراقبة حية** | شاهد تدفق الطلبات في الوقت الفعلي للتعرف على مشكلات الترجمة المتقطعة | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### مشكلات التنسيق الشائعة +### Common format issues -- **لا تظهر علامات التفكير** — تحقق مما إذا كان الموفر المستهدف يدعم التفكير وإعداد ميزانية التفكير -- **استدعاءات الأداة** — قد تؤدي بعض ترجمات التنسيق إلى إزالة الحقول غير المدعومة؛ تحقق في وضع الملعب -- **مطالبة النظام مفقودة** — يتعامل نظام Claude وGemini مع المطالبات بشكل مختلف؛ التحقق من إخراج الترجمة -- ** تقوم SDK بإرجاع سلسلة أولية بدلاً من الكائن ** - تم الإصلاح في الإصدار 1.1.0: تقوم أداة معالجة الاستجابة الآن بإزالة الحقول غير القياسية (`x_groq`، `usage_breakdown`، وما إلى ذلك) التي تتسبب في فشل التحقق من صحة OpenAI SDK Pydantic -- **GLM/ERNIE يرفض دور `system`** — تم إصلاحه في الإصدار 1.1.0: يقوم مُطبيع الدور تلقائيًا بدمج رسائل النظام في رسائل المستخدم للنماذج غير المتوافقة -- **`developer` لم يتم التعرف على الدور** — تم إصلاحه في الإصدار 1.1.0: تم تحويله تلقائيًا إلى `system` لمقدمي الخدمات غير التابعين لـ OpenAI -- **`json_schema` لا يعمل مع Gemini** — تم إصلاحه في الإصدار 1.1.0: `response_format` تم تحويله الآن إلى `responseMimeType` + `responseSchema` الخاص بـ Gemini\_\_ +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## إعدادات المرونة +## Resilience Settings -### لا يتم تشغيل حد المعدل التلقائي +### Auto rate-limit not triggering -- ينطبق حد المعدل التلقائي فقط على موفري مفاتيح واجهة برمجة التطبيقات (وليس OAuth/الاشتراك) -- تحقق من أن **الإعدادات → المرونة → ملفات تعريف الموفر** تم تمكين حد المعدل التلقائي -- تحقق مما إذا كان الموفر يعرض `429` رموز الحالة أو رؤوس `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### ضبط التراجع الأسي +### Tuning exponential backoff -تدعم ملفات تعريف الموفر هذه الإعدادات: +Provider profiles support these settings: -- **التأخير الأساسي** — وقت الانتظار الأولي بعد الفشل الأول (الافتراضي: 1 ثانية) -- **الحد الأقصى للتأخير** — الحد الأقصى لوقت الانتظار (الافتراضي: 30 ثانية) -- **المضاعف** — مقدار زيادة التأخير لكل فشل متتالي (الافتراضي: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### قطيع مضاد للرعد +### Anti-thundering herd -عندما تصل العديد من الطلبات المتزامنة إلى موفر محدود السعر، يستخدم OmniRoute تحديد المعدل التلقائي + mutex لإجراء تسلسل للطلبات ومنع حالات الفشل المتتالية. وهذا تلقائي لموفري مفاتيح API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## هل مازلت عالقًا؟ +## Optional RAG / LLM failure taxonomy (16 problems) -- **مشكلات GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **الهندسة المعمارية**: راجع [link](ARCHITECTURE.md) للحصول على التفاصيل الداخلية -- **مرجع واجهة برمجة التطبيقات**: راجع [link](API_REFERENCE.md) لجميع نقاط النهاية -- **لوحة معلومات الصحة**: تحقق من **لوحة المعلومات ← الصحة** لمعرفة حالة النظام في الوقت الفعلي -- **المترجم**: استخدم **لوحة المعلومات ← المترجم** لتصحيح مشكلات التنسيق +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/ar/USER_GUIDE.md b/docs/i18n/ar/USER_GUIDE.md index 3968fc6911..5a043224df 100644 --- a/docs/i18n/ar/USER_GUIDE.md +++ b/docs/i18n/ar/USER_GUIDE.md @@ -1,12 +1,12 @@ -# دليل المستخدم +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -الدليل الكامل لتكوين مقدمي الخدمات، وإنشاء المجموعات، ودمج أدوات CLI، ونشر OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## جدول المحتويات +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 لمحة سريعة عن الأسعار +## 💰 Pricing at a Glance -| الطبقة | مقدم | التكلفة | إعادة ضبط الحصص | الأفضل لـ | -| ---------------------------------- | ----------------------------------- | ---------------------- | ----------------------- | -------------------------------------- | -| **💳الإشتراك** | كلود كود (برو) | 20 دولارًا شهريًا | 5 ساعات + أسبوعي | اشتركت بالفعل | -| | الدستور الغذائي (زائد / برو) | 20-200 دولار شهريًا | 5 ساعات + أسبوعي | مستخدمي OpenAI | -| | الجوزاء CLI | **مجاني** | 180 ألف/شهر + 1 ألف/يوم | الجميع! | -| | جيثب مساعد الطيار | 10-19 دولارًا شهريًا | شهري | مستخدمي جيثب | -| **🔑 مفتاح واجهة برمجة التطبيقات** | ديب سيك | الدفع لكل استخدام | لا شيء | الاستدلال الرخيص | -| | جروك | الدفع لكل استخدام | لا شيء | الاستدلال فائق السرعة | -| | xAI (جروك) | الدفع لكل استخدام | لا شيء | جروك 4 المنطق | -| | ميسترال | الدفع لكل استخدام | لا شيء | النماذج التي يستضيفها الاتحاد الأوروبي | -| | الحيرة | الدفع لكل استخدام | لا شيء | البحث المعزز | -| | معا منظمة العفو الدولية | الدفع لكل استخدام | لا شيء | نماذج مفتوحة المصدر | -| | الألعاب النارية منظمة العفو الدولية | الدفع لكل استخدام | لا شيء | صور التدفق السريع | -| | المخيخ | الدفع لكل استخدام | لا شيء | سرعة على نطاق الرقاقة | -| | كوهير | الدفع لكل استخدام | لا شيء | الأمر R+ RAG | -| | نفيديا نيم | الدفع لكل استخدام | لا شيء | نماذج المؤسسات | -| **💰 رخيص** | جي إل إم-4.7 | 0.6 دولار/1 مليون | يوميا 10 صباحا | نسخة احتياطية للميزانية | -| | ميني ماكس M2.1 | 0.2 دولار/1 مليون | المتداول لمدة 5 ساعات | الخيار الأرخص | -| | كيمي ك2 | 9 دولارات شهريًا مسطحة | 10 مليون رمز/شهر | التكلفة المتوقعة | -| **🆓مجانًا** | اي فلو | $0 | غير محدود | 8 نماذج مجانية | -| | كوين | $0 | غير محدود | 3 نماذج مجانية | -| | كيرو | $0 | غير محدود | كلود مجاني | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 نصيحة احترافية:** ابدأ مع مجموعة Gemini CLI (180 ألفًا مجانًا شهريًا) + مجموعة iFlow (مجانية غير محدودة) = تكلفة 0 دولار! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 حالات الاستخدام +## 🎯 Use Cases -### الحالة 1: "لدي اشتراك Claude Pro" +### Case 1: "I have Claude Pro subscription" -**المشكلة:** تنتهي صلاحية الحصة غير المستخدمة، وحدود المعدل أثناء عملية الترميز المكثف +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### الحالة 2: "أريد تكلفة صفرية" +### Case 2: "I want zero cost" -**المشكلة:** لا أستطيع تحمل تكلفة الاشتراكات، وتحتاج إلى ترميز يعتمد على الذكاء الاصطناعي +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### الحالة 3: "أحتاج إلى تشفير على مدار 24 ساعة طوال أيام الأسبوع، دون انقطاع" +### Case 3: "I need 24/7 coding, no interruptions" -**المشكلة:** المواعيد النهائية، لا أستطيع تحمل فترات التوقف عن العمل +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### الحالة 4: "أريد ذكاءً اصطناعيًا مجانيًا في OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**المشكلة:** تحتاج إلى مساعد الذكاء الاصطناعي في تطبيقات المراسلة، مجانًا تمامًا +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 إعداد الموفر +## 📖 Provider Setup -### 🔐 مقدمي الاشتراكات +### 🔐 Subscription Providers -#### كلود كود (برو/ماكس) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**نصيحة احترافية:** استخدم Opus للمهام المعقدة، وSonnet للسرعة. OmniRoute يتتبع الحصة لكل نموذج! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (180 ألفًا شهريًا مجانًا!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**أفضل قيمة:** طبقة مجانية ضخمة! استخدم هذا قبل المستويات المدفوعة. +**Best Value:** Huge free tier! Use this before paid tiers. -#### مساعد جيثب +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 مقدمو خدمات رخيصون +### 💰 Cheap Providers -#### GLM-4.7 (إعادة التعيين اليومي، 0.6 دولار/1 مليون) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. قم بالتسجيل: [Zhipu AI](https://open.bigmodel.cn/) -2. احصل على مفتاح API من خطة الترميز -3. لوحة المعلومات → إضافة مفتاح واجهة برمجة التطبيقات: الموفر: `glm`، مفتاح واجهة برمجة التطبيقات: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**الاستخدام:** `glm/glm-4.7` — **نصيحة احترافية:** توفر خطة البرمجة حصة 3× بتكلفة 1/7! إعادة الضبط يوميًا الساعة 10:00 صباحًا. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (إعادة الضبط لمدة 5 ساعات، 0.20 دولار/1 مليون) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. قم بالتسجيل: [MiniMax](https://www.minimax.io/) -2. احصل على مفتاح API → لوحة المعلومات → إضافة مفتاح API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**الاستخدام:** `minimax/MiniMax-M2.1` — **نصيحة احترافية:** الخيار الأرخص للسياق الطويل (مليون رمز)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### كيمي K2 (شقة بقيمة 9 دولارات في الشهر) +#### Kimi K2 ($9/month flat) -1. الاشتراك: [Moonshot AI](https://platform.moonshot.ai/) -2. احصل على مفتاح API → لوحة المعلومات → إضافة مفتاح API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**الاستخدام:** `kimi/kimi-latest` — **نصيحة احترافية:** سعر ثابت قدره 9 دولارات شهريًا مقابل 10 ملايين رمز مميز = 0.90 دولارًا أمريكيًا/التكلفة الفعلية لمليون واحد! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 مقدمي الخدمة مجانًا +### 🆓 FREE Providers -#### iFlow (8 نماذج مجانية) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### كوين (3 موديلات مجانية) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### كيرو (كلود فري) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 المجموعات +## 🎨 Combos -### مثال 1: زيادة الاشتراك إلى الحد الأقصى → النسخ الاحتياطي الرخيص +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### المثال 2: مجاني فقط (بدون تكلفة) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 تكامل CLI +## 🔧 CLI Integration -### بيئة تطوير متكاملة للمؤشر +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### كلود كود +### Claude Code -تحرير `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Settings → Models → Advanced: } ``` -### كوديكس سطر الأوامر +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -تحرير `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ codex "your prompt" } ``` -**أو استخدم لوحة المعلومات:** أدوات CLI → OpenClaw → التكوين التلقائي +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### كلاين / متابعة / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 النشر +## 🚀 Deployment -### نشر VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### عامل الميناء +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,81 +403,84 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -بالنسبة للوضع المدمج مع المضيف مع ثنائيات CLI، راجع قسم Docker في المستندات الرئيسية. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### متغيرات البيئة +### Environment Variables -| متغير | الافتراضي | الوصف | -| --------------------- | ------------------------------------ | ---------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | سر توقيع JWT (**تغيير في الإنتاج**) | -| `INITIAL_PASSWORD` | `123456` | كلمة المرور الأولى لتسجيل الدخول | -| `DATA_DIR` | `~/.omniroute` | دليل البيانات (ديسيبل، الاستخدام، السجلات) | -| `PORT` | الإطار الافتراضي | منفذ الخدمة (`20128` في الأمثلة) | -| `HOSTNAME` | الإطار الافتراضي | ربط المضيف (إعدادات Docker الافتراضية هي `0.0.0.0`) | -| `NODE_ENV` | وقت التشغيل الافتراضي | قم بتعيين `production` للنشر | -| `BASE_URL` | `http://localhost:20128` | عنوان URL الأساسي الداخلي من جانب الخادم | -| `CLOUD_URL` | `https://omniroute.dev` | عنوان URL الأساسي لنقطة نهاية المزامنة السحابية | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | سر HMAC لمفاتيح API التي تم إنشاؤها | -| `REQUIRE_API_KEY` | `false` | فرض مفتاح Bearer API على `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | تمكين سجلات الطلب/الاستجابة | -| `AUTH_COOKIE_SECURE` | `false` | فرض ملف تعريف ارتباط المصادقة `Secure` (خلف الوكيل العكسي HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -للحصول على مرجع متغير البيئة الكامل، راجع [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 الموديلات المتوفرة +## 📊 Available Models
-عرض جميع الموديلات المتاحة +View all available models -**كود كلود (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**المخطوطة (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`، `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — مجانًا: `gc/gemini-3-flash-preview`، `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**مساعد GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — 0.6 دولار/1 مليون: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**ميني ماكس (`minimax/`)** — 0.2 دولار/1 مليون: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — مجانًا: `if/kimi-k2-thinking`، `if/qwen3-coder-plus`، `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**كوين (`qw/`)** — مجانًا: `qw/qwen3-coder-plus`، `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**كيرو (`kr/`)** — مجانًا: `kr/claude-sonnet-4.5`، `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` -**DeepSeek (`ds/`)**: `ds/deepseek-chat`، `ds/deepseek-reasoner` +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` -** جروك (`groq/`)**: `groq/llama-3.3-70b-versatile`، `groq/llama-4-maverick-17b-128e-instruct` +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` -**xAI (`xai/`)**: `xai/grok-4`، `xai/grok-4-0709-fast-reasoning`، `xai/grok-code-mini` +**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**ميسترال (`mistral/`)**: `mistral/mistral-large-2501`، `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**الحيرة (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -** معًا الذكاء الاصطناعي (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**الذكاء الاصطناعي للألعاب النارية (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -** سيريبراس (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**الترابط (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` -** نفيديا نيم (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
--- -## 🧩 ميزات متقدمة +## 🧩 Advanced Features -### نماذج مخصصة +### Custom Models -أضف أي معرف نموذج إلى أي مزود دون انتظار تحديث التطبيق: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -أو استخدم لوحة المعلومات: **المزودون → [الموفر] → النماذج المخصصة**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### مسارات موفر مخصصة +### Dedicated Provider Routes -توجيه الطلبات مباشرة إلى موفر محدد مع التحقق من صحة النموذج: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -تتم إضافة بادئة الموفر تلقائيًا في حالة فقدانها. تُرجع النماذج غير المتطابقة `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### تكوين وكيل الشبكة +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**الأسبقية:** خاص بالمفتاح ← خاص بالسرد والسرد ← خاص بالموفر ← عالمي ← البيئة. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### واجهة برمجة تطبيقات الكتالوج النموذجي +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -إرجاع النماذج المجمعة حسب الموفر مع الأنواع (`chat`، `embedding`، `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### المزامنة السحابية +### Cloud Sync -- موفري المزامنة والمجموعات والإعدادات عبر الأجهزة -- مزامنة الخلفية التلقائية مع انتهاء المهلة + الفشل السريع -- تفضيل جانب الخادم `BASE_URL`/`CLOUD_URL` في الإنتاج +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (المرحلة 9) +### LLM Gateway Intelligence (Phase 9) -- **ذاكرة التخزين المؤقت الدلالية** — ذاكرة تخزين مؤقت تلقائية غير متدفقة، درجة الحرارة = 0 استجابات (تجاوز باستخدام `X-OmniRoute-No-Cache: true`) -- **صلاحية الطلب** — إلغاء تكرار الطلبات خلال 5 ثوانٍ عبر رأس `Idempotency-Key` أو `X-Request-Id` -- **تتبع التقدم** — الاشتراك في أحداث SSE `event: progress` عبر رأس `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### ملعب المترجم +### Translator Playground -الوصول عبر **لوحة المعلومات → المترجم**. تصحيح الأخطاء وتصور كيفية قيام OmniRoute بترجمة طلبات واجهة برمجة التطبيقات (API) بين مقدمي الخدمة. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| الوضع | الغرض | -| -------------------- | ----------------------------------------------------------------------------- | -| **ساحة اللعب** | حدد تنسيقات المصدر/الهدف، والصق طلبًا، وشاهد المخرجات المترجمة على الفور | -| ** اختبار الدردشة ** | أرسل رسائل الدردشة المباشرة من خلال الوكيل وافحص دورة الطلب/الاستجابة الكاملة | -| ** مقعد الاختبار ** | قم بإجراء اختبارات مجمعة عبر مجموعات تنسيقات متعددة للتحقق من صحة الترجمة | -| **مراقبة حية** | شاهد الترجمات في الوقت الفعلي أثناء تدفق الطلبات عبر الوكيل | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**حالات الاستخدام:** +**Use cases:** -- تصحيح سبب فشل مجموعة محددة من العميل/الموفر -- التحقق من ترجمة علامات التفكير واستدعاءات الأدوات ومطالبات النظام بشكل صحيح -- مقارنة اختلافات التنسيق بين تنسيقات OpenAI وClaude وGemini وResponsions API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### استراتيجيات التوجيه +### Routing Strategies -قم بالتكوين عبر **لوحة المعلومات → الإعدادات → التوجيه**. +Configure via **Dashboard → Settings → Routing**. -| استراتيجية | الوصف | -| ------------------------ | ---------------------------------------------------------------------------------------- | -| ** املأ أولا ** | يستخدم الحسابات بترتيب الأولوية — يعالج الحساب الأساسي جميع الطلبات حتى تصبح غير متاحة | -| ** راوند روبن ** | للتنقل عبر جميع الحسابات بحد ثابت قابل للتكوين (الافتراضي: 3 مكالمات لكل حساب) | -| **P2C (قوة الاختيارين)** | يختار حسابين عشوائيين ويوجهك إلى الحساب الأكثر صحة - الأرصدة محملة بالوعي الصحي | -| **عشوائي** | تحديد حساب عشوائيًا لكل طلب باستخدام خلط Fisher-Yates | -| **الأقل استخدامًا** | التوجيهات إلى الحساب ذو الطابع الزمني الأقدم `lastUsedAt`، مع توزيع حركة المرور بالتساوي | -| **التكلفة الأمثل** | التوجيهات إلى الحساب ذي أقل قيمة أولوية، مع تحسين موفري الخدمة الأقل تكلفة | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### الأسماء المستعارة لنموذج البدل +#### Wildcard Model Aliases -قم بإنشاء أنماط أحرف البدل لإعادة تعيين أسماء النماذج: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -تدعم أحرف البدل `*` (أي أحرف) و`?` (حرف واحد). +Wildcards support `*` (any characters) and `?` (single character). -#### سلاسل احتياطية +#### Fallback Chains -تحديد السلاسل الاحتياطية العالمية التي تنطبق على جميع الطلبات: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### المرونة وقواطع الدائرة +### Resilience & Circuit Breakers -قم بالتكوين عبر **لوحة المعلومات → الإعدادات → المرونة**. +Configure via **Dashboard → Settings → Resilience**. -تطبق OmniRoute المرونة على مستوى المزود من خلال أربعة مكونات: +OmniRoute implements provider-level resilience with four components: -1. **ملفات تعريف الموفر** — التكوين لكل موفر لـ: - - عتبة الفشل (كم عدد حالات الفشل قبل الفتح) - - مدة التهدئة - - حساسية الكشف عن حد المعدل - - معلمات التراجع الأسي +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **حدود المعدل القابلة للتحرير** — الإعدادات الافتراضية على مستوى النظام قابلة للتكوين في لوحة المعلومات: - - **الطلبات في الدقيقة (RPM)** — الحد الأقصى للطلبات في الدقيقة لكل حساب - - **الحد الأدنى للوقت بين الطلبات** — الحد الأدنى للفجوة بالمللي ثانية بين الطلبات - - **الحد الأقصى للطلبات المتزامنة** — الحد الأقصى للطلبات المتزامنة لكل حساب - - انقر **تحرير** للتعديل، ثم **حفظ** أو **إلغاء**. تستمر القيم عبر واجهة برمجة تطبيقات المرونة. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **قاطع الدائرة** — يتتبع حالات الفشل لكل مزود ويفتح الدائرة تلقائيًا عند الوصول إلى الحد الأدنى: - - **مغلق** (صحي) — تتدفق الطلبات بشكل طبيعي - - **مفتوح** — تم حظر الموفر مؤقتًا بعد الفشل المتكرر - - **HALF_OPEN** — اختبار ما إذا كان الموفر قد استعاد عافيته +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **السياسات والمعرفات المقفلة** — تعرض حالة قاطع الدائرة والمعرفات المقفلة مع إمكانية إلغاء القفل بالقوة. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **الاكتشاف التلقائي لحدود المعدل** — يراقب الرؤوس `429` و`Retry-After` لتجنب الوصول إلى حدود معدل الموفر بشكل استباقي. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**نصيحة احترافية:** استخدم زر **إعادة تعيين الكل** لمسح جميع قواطع الدائرة وفترات التباطؤ عندما يتعافى المزود من انقطاع الخدمة. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### تصدير / استيراد قاعدة البيانات +### Database Export / Import -إدارة النسخ الاحتياطية لقاعدة البيانات في **لوحة المعلومات → الإعدادات → النظام والتخزين**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| العمل | الوصف | -| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| **تصدير قاعدة البيانات** | يقوم بتنزيل قاعدة بيانات SQLite الحالية كملف `.sqlite` | -| **تصدير الكل (.tar.gz)** | تنزيل أرشيف نسخ احتياطي كامل بما في ذلك: قاعدة البيانات، والإعدادات، والمجموعات، واتصالات الموفر (بدون بيانات اعتماد)، وبيانات تعريف مفتاح API | -| **استيراد قاعدة البيانات** | قم بتحميل ملف `.sqlite` لاستبدال قاعدة البيانات الحالية. يتم إنشاء نسخة احتياطية للاستيراد المسبق تلقائيًا | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**التحقق من صحة الاستيراد:** يتم التحقق من صحة الملف المستورد للتأكد من سلامته (فحص براغما SQLite)، والجداول المطلوبة (`provider_connections`، `provider_nodes`، `combos`، `api_keys`)، والحجم (100 ميجابايت كحد أقصى). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**حالات الاستخدام:** +**Use Cases:** -- ترحيل OmniRoute بين الأجهزة -- إنشاء نسخ احتياطية خارجية للتعافي من الكوارث -- مشاركة التكوينات بين أعضاء الفريق (تصدير الكل → مشاركة الأرشيف) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### لوحة تحكم الإعدادات +### Settings Dashboard -يتم تنظيم صفحة الإعدادات في 5 علامات تبويب لسهولة التنقل: +The settings page is organized into 5 tabs for easy navigation: -| علامة التبويب | المحتويات | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| **الأمن** | إعدادات تسجيل الدخول/كلمة المرور، والتحكم في الوصول إلى IP، ومصادقة API لـ `/models`، وحظر الموفر | -| **التوجيه** | استراتيجية التوجيه العالمية (6 خيارات)، والأسماء المستعارة لنماذج أحرف البدل، والسلاسل الاحتياطية، وافتراضيات التحرير والسرد | -| **المرونة** | ملفات تعريف الموفر، وحدود الأسعار القابلة للتحرير، وحالة قاطع الدائرة، والسياسات والمعرفات المقفلة | -| **الذكاء الاصطناعي** | تكوين ميزانية التفكير، والحقن الفوري للنظام العالمي، وإحصائيات ذاكرة التخزين المؤقت السريعة | -| **متقدم** | تكوين الوكيل العالمي (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### إدارة التكاليف والميزانية +### Costs & Budget Management -الوصول عبر **لوحة التحكم ← التكاليف**. +Access via **Dashboard → Costs**. -| علامة التبويب | الغرض | -| ------------- | ------------------------------------------------------------------------------------------------ | -| **الميزانية** | قم بتعيين حدود الإنفاق لكل مفتاح API باستخدام ميزانيات يومية/أسبوعية/شهرية وتتبع في الوقت الفعلي | -| **التسعير** | عرض وتحرير إدخالات تسعير النموذج - التكلفة لكل ألف رمز إدخال/إخراج لكل مزود | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**تتبع التكلفة:** يقوم كل طلب بتسجيل استخدام الرمز المميز وحساب التكلفة باستخدام جدول التسعير. عرض التفاصيل في **لوحة المعلومات → الاستخدام** حسب الموفر والطراز ومفتاح واجهة برمجة التطبيقات. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### النسخ الصوتي +### Audio Transcription -يدعم OmniRoute النسخ الصوتي عبر نقطة النهاية المتوافقة مع OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -الموفرون المتاحون: **Deepgram** (`deepgram/`)، **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### استراتيجيات موازنة التحرير والسرد +### Combo Balancing Strategies -قم بتكوين التوازن لكل مجموعة في **لوحة المعلومات → المجموعات → إنشاء/تحرير → الإستراتيجية**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| استراتيجية | الوصف | -| ------------------- | ---------------------------------------------------------------------------------------------- | -| **جولة روبن** | يدور عبر النماذج بالتتابع | -| **الأولوية** | يحاول دائمًا النموذج الأول؛ لا يعود إلا على الخطأ | -| **عشوائي** | يختار نموذجًا عشوائيًا من المجموعة لكل طلب | -| **المرجح** | تعتمد المسارات بشكل متناسب على الأوزان المخصصة لكل نموذج | -| **الأقل استخدامًا** | التوجيهات إلى النموذج الذي يحتوي على أقل عدد من الطلبات الأخيرة (يستخدم مقاييس التحرير والسرد) | -| **التكلفة الأمثل** | الطرق إلى أرخص طراز متاح (يستخدم جدول التسعير) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -يمكن ضبط إعدادات التحرير والسرد العامة في **لوحة المعلومات → الإعدادات → التوجيه → إعدادات التحرير والسرد الافتراضية**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### لوحة المعلومات الصحية +### Health Dashboard -الوصول عبر **لوحة التحكم → الصحة**. نظرة عامة على صحة النظام في الوقت الحقيقي مع 6 بطاقات: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| بطاقة | ما يظهر | -| ---------------------------------- | -------------------------------------------------------------- | -| **حالة النظام** | وقت التشغيل، الإصدار، استخدام الذاكرة، دليل البيانات | -| ** صحة المزود ** | حالة قاطع الدائرة الكهربائية لكل مزود (مغلق/مفتوح/نصف مفتوح) | -| ** حدود المعدل ** | فترات تهدئة حد المعدل النشط لكل حساب مع الوقت المتبقي | -| ** عمليات التأمين النشطة ** | تم حظر مقدمي الخدمة مؤقتًا بواسطة سياسة التأمين | -| ** ذاكرة التخزين المؤقت للتوقيع ** | إحصائيات إلغاء البيانات المكررة (المفاتيح النشطة، معدل الدخول) | -| ** قياس زمن الوصول ** | p50/p95/p99 تجميع زمن الوصول لكل مزود | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**نصيحة احترافية:** يتم تحديث صفحة الصحة تلقائيًا كل 10 ثوانٍ. استخدم بطاقة قاطع الدائرة لتحديد مقدمي الخدمة الذين يواجهون مشكلات. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/bg/API_REFERENCE.md b/docs/i18n/bg/API_REFERENCE.md index 4c600f7237..b795722c11 100644 --- a/docs/i18n/bg/API_REFERENCE.md +++ b/docs/i18n/bg/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Справка за API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Пълна справка за всички крайни точки на OmniRoute API. +Complete reference for all OmniRoute API endpoints. --- -## Съдържание +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## Завършвания на чат +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Персонализирани заглавки +### Custom Headers -| Заглавка | Посока | Описание | -| ------------------------ | ------- | ------------------------------------------ | -| `X-OmniRoute-No-Cache` | Заявка | Задайте `true` за заобикаляне на кеша | -| `X-OmniRoute-Progress` | Заявка | Задайте `true` за събития за прогрес | -| `Idempotency-Key` | Заявка | Ключ за дедупиране (5s прозорец) | -| `X-Request-Id` | Заявка | Алтернативен дедуп ключ | -| `X-OmniRoute-Cache` | Отговор | `HIT` или `MISS` (без поточно предаване) | -| `X-OmniRoute-Idempotent` | Отговор | `true` ако е дедупликиран | -| `X-OmniRoute-Progress` | Отговор | `enabled` ако проследяване на напредъка на | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Вграждания +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Налични доставчици: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Генериране на изображения +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Налични доставчици: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Списък с модели +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Крайни точки за съвместимост +## Compatibility Endpoints -| Метод | Път | Формат | -| ---------- | --------------------------- | -------------------------- | -| ПУБЛИКАЦИЯ | `/v1/chat/completions` | OpenAI | -| ПУБЛИКАЦИЯ | `/v1/messages` | Антропен | -| ПУБЛИКАЦИЯ | `/v1/responses` | OpenAI отговори | -| ПУБЛИКАЦИЯ | `/v1/embeddings` | OpenAI | -| ПУБЛИКАЦИЯ | `/v1/images/generations` | OpenAI | -| ВЗЕМЕТЕ | `/v1/models` | OpenAI | -| ПУБЛИКАЦИЯ | `/v1/messages/count_tokens` | Антропен | -| ВЗЕМЕТЕ | `/v1beta/models` | Близнаци | -| ПУБЛИКАЦИЯ | `/v1beta/models/{...path}` | Gemini генерира съдържание | -| ПУБЛИКАЦИЯ | `/v1/api/chat` | Олама | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Специализирани маршрути на доставчик +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Префиксът на доставчика се добавя автоматично, ако липсва. Несъответстващите модели връщат `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Семантичен кеш +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Пример за отговор: +Response example: ```json { @@ -162,154 +162,164 @@ DELETE /api/cache --- -## Табло за управление и управление +## Dashboard & Management -### Удостоверяване +### Authentication -| Крайна точка | Метод | Описание | -| ----------------------------- | ------------- | ---------------------------------- | -| `/api/auth/login` | ПУБЛИКАЦИЯ | Вход | -| `/api/auth/logout` | ПУБЛИКАЦИЯ | Изход | -| `/api/settings/require-login` | ВЗЕМИ/ПОСТАВИ | Изисква се превключване на влизане | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Управление на доставчика +### Provider Management -| Крайна точка | Метод | Описание | -| ---------------------------- | -------------------------------- | ---------------------------------------- | -| `/api/providers` | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ | Списък / създаване на доставчици | -| `/api/providers/[id]` | ПОЛУЧАВАНЕ/ПОСТАВЯНЕ/ИЗТРИВАНЕ | Управление на доставчик | -| `/api/providers/[id]/test` | ПУБЛИКАЦИЯ | Тествайте връзката с доставчик | -| `/api/providers/[id]/models` | ВЗЕМЕТЕ | Избройте модели на доставчици | -| `/api/providers/validate` | ПУБЛИКАЦИЯ | Проверка на конфигурацията на доставчика | -| `/api/provider-nodes*` | Различни | Управление на възел на доставчик | -| `/api/provider-models` | ПОЛУЧАВАНЕ/ПУБЛИКУВАНЕ/ИЗТРИВАНЕ | Персонализирани модели | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth потоци +### OAuth Flows -| Крайна точка | Метод | Описание | -| -------------------------------- | -------- | ------------------------------ | -| `/api/oauth/[provider]/[action]` | Различни | Специфичен за доставчика OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Маршрутизиране и конфигурация +### Routing & Config -| Крайна точка | Метод | Описание | -| --------------------- | -------------------- | -------------------------------- | -| `/api/models/alias` | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ | Псевдоними на модели | -| `/api/models/catalog` | ВЗЕМЕТЕ | Всички модели по доставчик + тип | -| `/api/combos*` | Различни | Комбо управление | -| `/api/keys*` | Различни | Управление на API ключове | -| `/api/pricing` | ВЗЕМЕТЕ | Моделна цена | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Използване и анализ +### Usage & Analytics -| Крайна точка | Метод | Описание | -| --------------------------- | ------- | ----------------------- | -| `/api/usage/history` | ВЗЕМЕТЕ | История на използването | -| `/api/usage/logs` | ВЗЕМЕТЕ | Дневници за използване | -| `/api/usage/request-logs` | ВЗЕМЕТЕ | Дневници на ниво заявка | -| `/api/usage/[connectionId]` | ВЗЕМЕТЕ | Използване на връзка | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Настройки +### Settings -| Крайна точка | Метод | Описание | -| ------------------------------- | ------------- | -------------------------------------- | -| `/api/settings` | ВЗЕМИ/ПОСТАВИ | Общи настройки | -| `/api/settings/proxy` | ВЗЕМИ/ПОСТАВИ | Конфигурация на мрежов прокси | -| `/api/settings/proxy/test` | ПУБЛИКАЦИЯ | Тествайте прокси връзката | -| `/api/settings/ip-filter` | ВЗЕМИ/ПОСТАВИ | Списък с разрешени/блокирани IP адреси | -| `/api/settings/thinking-budget` | ВЗЕМИ/ПОСТАВИ | Бюджет на жетон за разсъждение | -| `/api/settings/system-prompt` | ВЗЕМИ/ПОСТАВИ | Глобална системна подкана | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Мониторинг +### Monitoring -| Крайна точка | Метод | Описание | -| ------------------------ | -------------------- | ----------------------------- | -| `/api/sessions` | ВЗЕМЕТЕ | Проследяване на активна сесия | -| `/api/rate-limits` | ВЗЕМЕТЕ | Лимити за лихви по сметка | -| `/api/monitoring/health` | ВЗЕМЕТЕ | Здравна проверка | -| `/api/cache` | ПОЛУЧАВАНЕ/ИЗТРИВАНЕ | Кеш статистики / изчистване | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Архивиране и експортиране/импортиране +### Backup & Export/Import -| Крайна точка | Метод | Описание | -| --------------------------- | ---------- | ------------------------------------------------ | -| `/api/db-backups` | ВЗЕМЕТЕ | Избройте наличните резервни копия | -| `/api/db-backups` | ПОСТАВЕТЕ | Създайте ръчно архивиране | -| `/api/db-backups` | ПУБЛИКАЦИЯ | Възстановяване от конкретен архив | -| `/api/db-backups/export` | ВЗЕМЕТЕ | Изтегляне на база данни като .sqlite файл | -| `/api/db-backups/import` | ПУБЛИКАЦИЯ | Качете .sqlite файл, за да замените базата данни | -| `/api/db-backups/exportAll` | ВЗЕМЕТЕ | Изтеглете пълното архивиране като .tar.gz архив | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Облачно синхронизиране +### Cloud Sync -| Крайна точка | Метод | Описание | -| ---------------------- | ---------- | ---------------------------------- | -| `/api/sync/cloud` | Различни | Операции за синхронизиране в облак | -| `/api/sync/initialize` | ПУБЛИКАЦИЯ | Инициализиране на синхронизиране | -| `/api/cloud/*` | Различни | Облачно управление | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI инструменти +### CLI Tools -| Крайна точка | Метод | Описание | -| ---------------------------------- | ------- | ---------------------- | -| `/api/cli-tools/claude-settings` | ВЗЕМЕТЕ | Клод CLI състояние | -| `/api/cli-tools/codex-settings` | ВЗЕМЕТЕ | Codex CLI състояние | -| `/api/cli-tools/droid-settings` | ВЗЕМЕТЕ | Droid CLI състояние | -| `/api/cli-tools/openclaw-settings` | ВЗЕМЕТЕ | OpenClaw CLI състояние | -| `/api/cli-tools/runtime/[toolId]` | ВЗЕМЕТЕ | Generic CLI runtime | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -CLI отговорите включват: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Устойчивост и ограничения на скоростта +### ACP Agents -| Крайна точка | Метод | Описание | -| ----------------------- | ------------- | --------------------------------------------- | -| `/api/resilience` | ВЗЕМИ/ПОСТАВИ | Вземете/актуализирайте профили за устойчивост | -| `/api/resilience/reset` | ПУБЛИКАЦИЯ | Нулиране на прекъсвачи | -| `/api/rate-limits` | ВЗЕМЕТЕ | Състояние на ограничение на лимита по сметка | -| `/api/rate-limit` | ВЗЕМЕТЕ | Конфигурация на глобален лимит на скоростта | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Оценки +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Крайна точка | Метод | Описание | -| ------------ | -------------------- | --------------------------------------- | -| `/api/evals` | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ | Избройте eval пакети / изпълнете оценка | +### Resilience & Rate Limits -### Политики +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Крайна точка | Метод | Описание | -| --------------- | -------------------------------- | ----------------------------------------- | -| `/api/policies` | ПОЛУЧАВАНЕ/ПУБЛИКУВАНЕ/ИЗТРИВАНЕ | Управление на правилата за маршрутизиране | +### Evals -### Съответствие +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Крайна точка | Метод | Описание | -| --------------------------- | ------- | -------------------------------------------------- | -| `/api/compliance/audit-log` | ВЗЕМЕТЕ | Дневник за проверка на съответствието (последно N) | +### Policies -### v1beta (съвместим с Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Крайна точка | Метод | Описание | -| -------------------------- | ---------- | ------------------------------------- | -| `/v1beta/models` | ВЗЕМЕТЕ | Избройте модели във формат Gemini | -| `/v1beta/models/{...path}` | ПУБЛИКАЦИЯ | Gemini `generateContent` крайна точка | +### Compliance -Тези крайни точки отразяват API формата на Gemini за клиенти, които очакват естествена съвместимост с Gemini SDK. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### Вътрешен/системен API +### v1beta (Gemini-Compatible) -| Крайна точка | Метод | Описание | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `/api/init` | ВЗЕМЕТЕ | Проверка за инициализация на приложението (използва се при първото стартиране) | -| `/api/tags` | ВЗЕМЕТЕ | Тагове за модели, съвместими с Ollama (за клиенти на Ollama) | -| `/api/restart` | ПУБЛИКАЦИЯ | Задейства грациозно рестартиране на сървъра | -| `/api/shutdown` | ПУБЛИКАЦИЯ | Задействайте грациозно изключване на сървъра | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Забележка:** Тези крайни точки се използват вътрешно от системата или за съвместимост с клиента Ollama. Те обикновено не се извикват от крайните потребители. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Аудио транскрипция +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Транскрибирайте аудио файлове с помощта на Deepgram или AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Заявка:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Отговор:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Поддържани доставчици:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Поддържани формати:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Съвместимост с Ollama +## Ollama Compatibility -За клиенти, които използват API формат на Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Заявките се превеждат автоматично между Ollama и вътрешни формати. +Requests are automatically translated between Ollama and internal formats. --- -## Телеметрия +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Отговор:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Бюджет +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Наличност на модела +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Обработка на заявка +## Request Processing -1. Клиентът изпраща заявка до `/v1/*` -2. Обработчикът на маршрута извиква `handleChat`, `handleEmbedding`, `handleAudioTranscription` или `handleImageGeneration` -3. Моделът е разрешен (директен доставчик/модел или псевдоним/комбо) -4. Идентификационни данни, избрани от локална база данни с филтриране на наличността на акаунта -5. За чат: `handleChatCore` — откриване на формат, превод, проверка на кеша, проверка на идемпотентност -6. Изпълнителят на доставчика изпраща заявка нагоре по веригата -7. Отговор, преведен обратно във формат на клиента (чат) или върнат такъв, какъвто е (вграждания/изображения/аудио) -8. Записано използване/регистриране -9. Резервният вариант се прилага при грешки според комбо правилата +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Пълна справка за архитектурата: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Удостоверяване +## Authentication -- Маршрутите на таблото за управление (`/dashboard/*`) използват бисквитка `auth_token` -- Входът използва запазен хеш на паролата; връщане към `INITIAL_PASSWORD` -- `requireLogin` превключваем чрез `/api/settings/require-login` -- `/v1/*` маршрутите по избор изискват Bearer API ключ, когато `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/bg/ARCHITECTURE.md b/docs/i18n/bg/ARCHITECTURE.md index 5229b49fa8..258d62df53 100644 --- a/docs/i18n/bg/ARCHITECTURE.md +++ b/docs/i18n/bg/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Архитектура OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Последна актуализация: 2026-02-18_ +_Last updated: 2026-03-04_ -## Резюме +## Executive Summary -OmniRoute е локален AI маршрутизиращ шлюз и табло за управление, изградено на Next.js. -Той осигурява една крайна точка, съвместима с OpenAI (`/v1/*`) и маршрутизира трафика през множество доставчици нагоре по веригата с превод, резервен вариант, опресняване на токени и проследяване на използването. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Основни възможности: +Core capabilities: -- OpenAI-съвместима API повърхност за CLI/инструменти (28 доставчици) -- Превод на заявка/отговор във форматите на доставчика -- Резервна комбинация от модели (последователност от няколко модела) -- Резервен вариант на ниво акаунт (мулти акаунт на доставчик) -- OAuth + API-ключ управление на връзката на доставчика -- Генериране на вграждане чрез `/v1/embeddings` (6 доставчика, 9 модела) -- Генериране на изображения чрез `/v1/images/generations` (4 доставчика, 9 модела) -- Мислен синтактичен анализ на етикет (`...`) за модели на разсъждение -- Дезинфекция на отговора за стриктна съвместимост с OpenAI SDK -- Нормализиране на ролята (разработчик→система, система→потребител) за съвместимост между доставчици -- Структурирано преобразуване на изход (json_schema → Gemini responseSchema) -- Локална устойчивост за доставчици, ключове, псевдоними, комбинации, настройки, ценообразуване -- Проследяване на използване/разходи и регистриране на заявки -- Допълнителна облачна синхронизация за синхронизиране на множество устройства/състояние -- Списък с разрешени/блокирани IP адреси за контрол на достъпа до API -- Мислещо управление на бюджета (преминаване/автоматично/персонализирано/адаптивно) -- Бързо инжектиране на глобалната система -- Проследяване на сесии и пръстови отпечатъци -- Подобрено ограничаване на скоростта за всеки акаунт със специфични за доставчика профили -- Модел на прекъсвача за устойчивост на доставчика -- Анти-гръмотевична стадна защита с mutex заключване -- Кеш за дедупликация на заявки, базиран на подпис -- Слой на домейна: наличност на модела, правила за разходите, резервна политика, политика за блокиране -- Устойчивост на състоянието на домейна (кеш за запис на SQLite за резервни варианти, бюджети, блокировки, прекъсвачи на верига) -- Механизъм за правила за централизирана оценка на заявката (заключване → бюджет → резервен) -- Заявка за телеметрия с p50/p95/p99 агрегиране на латентност -- ID на корелация (X-Request-Id) за проследяване от край до край -- Регистриране на одит за съответствие с отказ за всеки API ключ -- Eval framework за осигуряване на качеството на LLM -- Resilience UI табло със статус на прекъсвача в реално време -- Модулни OAuth доставчици (12 отделни модула под `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Основен модел на изпълнение: +Primary runtime model: -- Маршрутите на приложението Next.js под `src/app/api/*` прилагат както API на таблото за управление, така и API за съвместимост -- Споделено SSE/маршрутизиращо ядро в `src/sse/*` + `open-sse/*` обработва изпълнението на доставчика, превода, стрийминг, резервен вариант и използване +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Обхват и граници +## Scope and Boundaries -### В обхват +### In Scope -- Време за изпълнение на локален шлюз -- API за управление на таблото -- Удостоверяване на доставчика и опресняване на токена -- Заявка за превод и SSE стрийминг -- Локално състояние + постоянство на използване -- Допълнителна синхронизация в облака +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Извън обхвата +### Out of Scope -- Внедряване на облачна услуга зад `NEXT_PUBLIC_CLOUD_URL` -- SLA/контролна равнина на доставчика извън локалния процес -- Самите външни CLI двоични файлове (Claude CLI, Codex CLI и т.н.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Системен контекст на високо ниво +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Основни компоненти по време на изпълнение +## Core Runtime Components -## 1) API и слой за маршрутизиране (Маршрути на приложението Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Основни директории: +Main directories: -- `src/app/api/v1/*` и `src/app/api/v1beta/*` за API за съвместимост -- `src/app/api/*` за API за управление/конфигуриране -- Следващото пренаписване в `next.config.mjs` преобразува `/v1/*` в `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Важни пътища за съвместимост: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — включва потребителски модели с `custom: true` -- `src/app/api/v1/embeddings/route.ts` — генериране на вграждане (6 доставчика) -- `src/app/api/v1/images/generations/route.ts` — генериране на изображения (4+ доставчици, вкл. Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — специален чат за всеки доставчик -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — специални вграждания за всеки доставчик -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — специални изображения за всеки доставчик +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Домейни за управление: +Management domains: -- Удостоверяване/настройки: `src/app/api/auth/*`, `src/app/api/settings/*` -- Доставчици/връзки: `src/app/api/providers*` -- Възли на доставчик: `src/app/api/provider-nodes*` -- Персонализирани модели: `src/app/api/provider-models` (GET/POST/DELETE) -- Каталог с модели: `src/app/api/models/catalog` (GET) -- Прокси конфигурация: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Ключове/псевдоними/комбота/цени: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Използване: `src/app/api/usage/*` -- Синхронизиране/облак: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Помощни инструменти за CLI: `src/app/api/cli-tools/*` -- IP филтър: `src/app/api/settings/ip-filter` (GET/PUT) -- Бюджет за мислене: `src/app/api/settings/thinking-budget` (GET/PUT) -- Системна подкана: `src/app/api/settings/system-prompt` (GET/PUT) -- Сесии: `src/app/api/sessions` (GET) -- Ограничения на скоростта: `src/app/api/rate-limits` (GET) -- Устойчивост: `src/app/api/resilience` (GET/PATCH) — профили на доставчик, прекъсвач, състояние на ограничение на скоростта -- Нулиране на устойчивостта: `src/app/api/resilience/reset` (POST) — нулиране на прекъсвачи + охлаждане -- Кеш статистики: `src/app/api/cache/stats` (ПОЛУЧАВАНЕ/ИЗТРИВАНЕ) -- Наличност на модела: `src/app/api/models/availability` (GET/POST) -- Телеметрия: `src/app/api/telemetry/summary` (GET) -- Бюджет: `src/app/api/usage/budget` (GET/POST) -- Резервни вериги: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Одит за съответствие: `src/app/api/compliance/audit-log` (GET) -- Стойности: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Правила: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + ядро за превод +## 2) SSE + Translation Core -Основни модули на потока: +Main flow modules: -- Запис: `src/sse/handlers/chat.ts` -- Основна оркестрация: `open-sse/handlers/chatCore.ts` -- Адаптери за изпълнение на доставчика: `open-sse/executors/*` -- Откриване на формат/конфигурация на доставчика: `open-sse/services/provider.ts` -- Разбор/разрешаване на модела: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Резервна логика на акаунта: `open-sse/services/accountFallback.ts` -- Регистър на преводите: `open-sse/translator/index.ts` -- Трансформации на потока: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Извличане/нормализиране на използването: `open-sse/utils/usageTracking.ts` -- Мислен анализатор на етикети: `open-sse/utils/thinkTagParser.ts` -- Манипулатор за вграждане: `open-sse/handlers/embeddings.ts` -- Регистър на доставчика на вграждане: `open-sse/config/embeddingRegistry.ts` -- Манипулатор за генериране на изображения: `open-sse/handlers/imageGeneration.ts` -- Регистър на доставчика на изображения: `open-sse/config/imageRegistry.ts` -- Саниране на отговора: `open-sse/handlers/responseSanitizer.ts` -- Нормализация на ролята: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Услуги (бизнес логика): +Services (business logic): -- Избор/точкуване на акаунт: `open-sse/services/accountSelector.ts` -- Управление на жизнения цикъл на контекста: `open-sse/services/contextManager.ts` -- Налагане на IP филтър: `open-sse/services/ipFilter.ts` -- Проследяване на сесии: `open-sse/services/sessionManager.ts` -- Искане за дедупликация: `open-sse/services/signatureCache.ts` -- Системно бързо инжектиране: `open-sse/services/systemPrompt.ts` -- Мислещо управление на бюджета: `open-sse/services/thinkingBudget.ts` -- Маршрутизиране на модела със заместващи знаци: `open-sse/services/wildcardRouter.ts` -- Управление на лимита на скоростта: `open-sse/services/rateLimitManager.ts` -- Прекъсвач: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Модули на ниво домейн: +Domain layer modules: -- Наличност на модела: `src/lib/domain/modelAvailability.ts` -- Правила/бюджети за разходите: `src/lib/domain/costRules.ts` -- Резервна политика: `src/lib/domain/fallbackPolicy.ts` -- Комбо резолвер: `src/lib/domain/comboResolver.ts` -- Правила за блокиране: `src/lib/domain/lockoutPolicy.ts` -- Механизъм за правила: `src/domain/policyEngine.ts` — централизирано блокиране → бюджет → резервна оценка -- Каталог с кодове за грешки: `src/lib/domain/errorCodes.ts` -- ID на заявката: `src/lib/domain/requestId.ts` -- Време за изчакване на извличане: `src/lib/domain/fetchTimeout.ts` -- Заявка за телеметрия: `src/lib/domain/requestTelemetry.ts` -- Съответствие/одит: `src/lib/domain/compliance/index.ts` -- Евал бегач: `src/lib/domain/evalRunner.ts` -- Устойчивост на състоянието на домейна: `src/lib/db/domainState.ts` — SQLite CRUD за резервни вериги, бюджети, история на разходите, състояние на блокиране, прекъсвачи +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Модули за доставчик на OAuth (12 отделни файла под `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Индекс на регистъра: `src/lib/oauth/providers/index.ts` -- Индивидуални доставчици: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Тънка обвивка: `src/lib/oauth/providers.ts` — повторно експортиране от отделни модули +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Слой за устойчивост +## 3) Persistence Layer -Основно състояние DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- файл: `${DATA_DIR}/db.json` (или `$XDG_CONFIG_HOME/omniroute/db.json`, когато е зададено, в противен случай `~/.omniroute/db.json`) -- обекти: providerConnections, providerNodes, modelAliases, комбинации, apiKeys, настройки, ценообразуване, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -DB за използване: +Usage persistence: -- `src/lib/usageDb.ts` -- файлове: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- следва същата основна политика за директория като `localDb` (`DATA_DIR`, след това `XDG_CONFIG_HOME/omniroute`, когато е зададено) -- разложен на фокусирани подмодули: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -DB на състоянието на домейна (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — CRUD операции за състояние на домейна -- Таблици (създадени в `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Модел на кеша за запис: Картите в паметта са авторитетни по време на изпълнение; мутациите се записват синхронно в SQLite; състоянието се възстановява от DB при студен старт +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Удостоверяване + повърхности за сигурност +## 4) Auth + Security Surfaces -- Удостоверяване на бисквитките на таблото за управление: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Генериране/проверка на API ключ: `src/shared/utils/apiKey.ts` -- Тайните на доставчика се запазват в `providerConnections` записи -- Поддръжка на изходящ прокси чрез `open-sse/utils/proxyFetch.ts` (env vars) и `open-sse/utils/networkProxy.ts` (конфигурируем за всеки доставчик или глобално) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Синхронизиране в облак +## 5) Cloud Sync -- Инициализация на планировчика: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Периодична задача: `src/shared/services/cloudSyncScheduler.ts` -- Контролен маршрут: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Жизнен цикъл на заявка (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Комбо + Резервен поток на акаунт +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Резервните решения се управляват от `open-sse/services/accountFallback.ts` с помощта на кодове за състояние и евристика за съобщения за грешка. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Жизнен цикъл на внедряване на OAuth и опресняване на токени +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Опресняването по време на трафик на живо се изпълнява вътре в `open-sse/handlers/chatCore.ts` чрез изпълнител `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Жизнен цикъл на Cloud Sync (Активиране / Синхронизиране / Деактивиране) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Периодичното синхронизиране се задейства от `CloudSyncScheduler`, когато облакът е активиран. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Модел на данни и карта за съхранение +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Файлове за физическо съхранение: +Physical storage files: -- основно състояние: `${DATA_DIR}/db.json` (или `$XDG_CONFIG_HOME/omniroute/db.json`, когато е зададено, в противен случай `~/.omniroute/db.json`) -- статистика за използване: `${DATA_DIR}/usage.json` -- Редове на заявката: `${DATA_DIR}/log.txt` -- незадължителни сесии за преводач/заявка за отстраняване на грешки: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Топология на разполагане +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Съпоставяне на модул (критично за вземане на решения) +## Module Mapping (Decision-Critical) -### Модули за маршрут и API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API за съвместимост -- `src/app/api/v1/providers/[provider]/*`: специални маршрути за всеки доставчик (чат, вграждания, изображения) -- `src/app/api/providers*`: доставчик CRUD, валидиране, тестване -- `src/app/api/provider-nodes*`: персонализирано съвместимо управление на възли -- `src/app/api/provider-models`: персонализирано управление на модела (CRUD) -- `src/app/api/models/catalog`: пълен модел каталог API (всички типове групирани по доставчик) -- `src/app/api/oauth/*`: OAuth/код на устройство протича -- `src/app/api/keys*`: жизнен цикъл на локален API ключ -- `src/app/api/models/alias`: управление на псевдоними -- `src/app/api/combos*`: резервно комбо управление -- `src/app/api/pricing`: ценообразуване отменя за изчисляване на разходите -- `src/app/api/settings/proxy`: конфигурация на прокси (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: тест за изходяща прокси връзка (POST) -- `src/app/api/usage/*`: API за използване и регистрационни файлове -- `src/app/api/sync/*` + `src/app/api/cloud/*`: облачно синхронизиране и помощници в облака -- `src/app/api/cli-tools/*`: локални писатели/контролери на CLI конфигурация -- `src/app/api/settings/ip-filter`: списък с разрешени/блокирани IP адреси (GET/PUT) -- `src/app/api/settings/thinking-budget`: конфигурация на бюджета на мислещ токен (GET/PUT) -- `src/app/api/settings/system-prompt`: глобална системна подкана (GET/PUT) -- `src/app/api/sessions`: списък с активни сесии (GET) -- `src/app/api/rate-limits`: състояние на ограничение на скоростта на сметка (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Ядро за маршрутизиране и изпълнение +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: анализ на заявка, комбо обработка, цикъл за избор на акаунт -- `open-sse/handlers/chatCore.ts`: превод, изпращане на изпълнителя, обработка на повторен опит/опресняване, настройка на потока -- `open-sse/executors/*`: специфично за доставчика поведение на мрежата и формата +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Регистър за преводи и конвертори на формати +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: регистър на преводача и оркестрация -- Заявка за преводачи: `open-sse/translator/request/*` -- Преводачи на отговори: `open-sse/translator/response/*` -- Константи на формата: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Постоянство +### Persistence -- `src/lib/localDb.ts`: постоянна конфигурация/състояние -- `src/lib/usageDb.ts`: хронология на използването и регистрационни файлове на текущи заявки +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Покритие на изпълнител на доставчик (стратегически модел) +## Provider Executor Coverage (Strategy Pattern) -Всеки доставчик има специализиран изпълнител, разширяващ `BaseExecutor` (в `open-sse/executors/base.ts`), който осигурява изграждане на URL адрес, изграждане на заглавка, повторен опит с експоненциално забавяне, кукички за опресняване на идентификационни данни и метода за оркестрация `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Изпълнител | Доставчик(и) | Специална обработка | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Конфигурация на динамичен URL/заглавие за доставчик | -| `AntigravityExecutor` | Google Антигравитация | Идентификационни номера на персонализирани проекти/сесии, повторен опит след анализ | -| `CodexExecutor` | OpenAI Codex | Вкарва системни инструкции, налага усилие за разсъждение | -| `CursorExecutor` | Курсор IDE | ConnectRPC протокол, Protobuf кодиране, подписване на заявка чрез контролна сума | -| `GithubExecutor` | Копилот на GitHub | Опресняване на Copilot token, заглавки, имитиращи VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Киро | AWS EventStream двоичен формат → SSE конвертиране | -| `GeminiCLIExecutor` | Gemini CLI | Цикъл на опресняване на Google OAuth токен | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Всички други доставчици (включително персонализирани съвместими възли) използват `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Матрица за съвместимост на доставчика +## Provider Compatibility Matrix -| Доставчик | Формат | Удостоверяване | Поток | Непоточно | Опресняване на токена | API за използване | -| ----------------- | --------------- | ------------------------------ | ---------------- | --------- | --------------------- | ---------------------------- | -| Клод | Клод | API ключ / OAuth | ✅ | ✅ | ✅ | ⚠️ Само администратор | -| Близнаци | близнаци | API ключ / OAuth | ✅ | ✅ | ✅ | ⚠️ Облачна конзола | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Облачна конзола | -| Антигравитация | антигравитация | OAuth | ✅ | ✅ | ✅ | ✅ API с пълна квота | -| OpenAI | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| Кодекс | openai-отговори | OAuth | ✅ принуден | ❌ | ✅ | ✅ Ограничения на скоростта | -| Копилот на GitHub | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Моментни снимки на квоти | -| Курсор | курсор | Персонализирана контролна сума | ✅ | ✅ | ❌ | ❌ | -| Киро | киро | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Ограничения за използване | -| Куен | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ По заявка | -| iFlow | openai | OAuth (основен) | ✅ | ✅ | ✅ | ⚠️ По заявка | -| OpenRouter | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| GLM/Кими/МиниМакс | Клод | API ключ | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| Мистрал | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| Недоумение | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| Заедно AI | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| Фойерверки AI | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| Мозъци | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| Cohere | openai | API ключ | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API ключ | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Обхват на превод на формат +## Format Translation Coverage -Откритите изходни формати включват: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Целевите формати включват: +Target formats include: -- OpenAI чат/Отговори -- Клод -- Gemini/Gemini-CLI/Антигравитационен плик -- Киро -- Курсор +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -Преводите използват **OpenAI като хъб формат** — всички реализации преминават през OpenAI като междинен: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Преводите се избират динамично въз основа на формата на изходния полезен товар и целевия формат на доставчика. +Translations are selected dynamically based on source payload shape and provider target format. -Допълнителни слоеве за обработка в тръбопровода за превод: +Additional processing layers in the translation pipeline: -- **Дефектификация на отговора** — Премахва нестандартните полета от отговорите във формат OpenAI (както стрийминг, така и без стрийминг), за да се гарантира стриктно съответствие с SDK -- **Нормализиране на ролята** — Преобразува `developer` → `system` за цели, които не са OpenAI; обединява `system` → `user` за модели, които отхвърлят системната роля (GLM, ERNIE) -- **Извличане на мислен етикет** — Анализира `...` блокове от съдържание в поле `reasoning_content` -- **Структуриран изход** — Преобразува OpenAI `response_format.json_schema` в `responseMimeType` + `responseSchema` на Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Поддържани API крайни точки +## Supported API Endpoints -| Крайна точка | Формат | Манипулатор | -| -------------------------------------------------- | ------------------------- | ------------------------------------------------------------------ | -| `POST /v1/chat/completions` | OpenAI чат | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Съобщения на Клод | Същият манипулатор (автоматично разпознат) | -| `POST /v1/responses` | OpenAI отговори | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI вграждания | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Списък на модели | API маршрут | -| `POST /v1/images/generations` | OpenAI изображения | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Списък на модели | API маршрут | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI чат | Специализиран за всеки доставчик с валидиране на модел | -| `POST /v1/providers/{provider}/embeddings` | OpenAI вграждания | Специализиран за всеки доставчик с валидиране на модел | -| `POST /v1/providers/{provider}/images/generations` | OpenAI изображения | Специализиран за всеки доставчик с валидиране на модел | -| `POST /v1/messages/count_tokens` | Клод Токен Брой | API маршрут | -| `GET /v1/models` | Списък с модели на OpenAI | API маршрут (чат + вграждане + изображение + потребителски модели) | -| `GET /api/models/catalog` | Каталог | Всички модели, групирани по доставчик + тип | -| `POST /v1beta/models/*:streamGenerateContent` | Родом от Близнаци | API маршрут | -| `GET/PUT/DELETE /api/settings/proxy` | Прокси конфигурация | Конфигурация на мрежов прокси | -| `POST /api/settings/proxy/test` | Прокси връзка | Крайна точка на прокси тест за изправност/свързаност | -| `GET/POST/DELETE /api/provider-models` | Персонализирани модели | Персонализирано управление на модели за всеки доставчик | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Обходен манипулатор +## Bypass Handler -Обходният манипулатор (`open-sse/utils/bypassHandler.ts`) прихваща известни заявки за „изхвърляне“ от Claude CLI — пингове за загряване, извличане на заглавия и преброяване на токени — и връща **фалшив отговор**, без да консумира токени на доставчика нагоре по веригата. Това се задейства само когато `User-Agent` съдържа `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Тръбопровод за регистратор на заявки +## Request Logger Pipeline -Регистраторът на заявки (`open-sse/utils/requestLogger.ts`) осигурява 7-етапен конвейер за регистриране на грешки, деактивиран по подразбиране, активиран чрез `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Файловете се записват в `/logs//` за всяка сесия на заявка. +Files are written to `/logs//` for each request session. -## Режими на отказ и устойчивост +## Failure Modes and Resilience -## 1) Наличност на акаунт/доставчик +## 1) Account/Provider Availability -- изчакване на акаунта на доставчика при преходни/скоростни/удостоверителни грешки -- резервен акаунт преди неуспешна заявка -- резервен комбиниран модел, когато пътят на текущия модел/доставчик е изчерпан +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Изтичане на токена +## 2) Token Expiry -- предварителна проверка и опресняване с повторен опит за опресняващи доставчици -- 401/403 повторен опит след опит за опресняване в основния път +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Безопасност на потока +## 3) Stream Safety -- контролер на потоци, който се изключва -- поток за превод с промиване в края на потока и обработка на `[DONE]` -- резервна оценка на използването, когато липсват метаданни за използване на доставчика +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Влошаване на облачната синхронизация +## 4) Cloud Sync Degradation -- появяват се грешки при синхронизиране, но локалното изпълнение продължава -- планировчикът има логика с възможност за повторен опит, но периодичното изпълнение в момента извиква синхронизиране с един опит по подразбиране +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Цялост на данните +## 5) Data Integrity -- Миграция/поправка на DB форма за липсващи ключове -- повредени предпазни мерки за нулиране на JSON за localDb и usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Наблюдаемост и оперативни сигнали +## Observability and Operational Signals -Източници на видимост по време на изпълнение: +Runtime visibility sources: -- регистрационни файлове на конзолата от `src/sse/utils/logger.ts` -- агрегати за използване на заявка в `usage.json` -- влизане на състоянието на текстова заявка `log.txt` -- незадължителни дълбоки регистрационни файлове за заявка/превод под `logs/`, когато `ENABLE_REQUEST_LOGS=true` -- крайни точки за използване на таблото за управление (`/api/usage/*`) за потребление на UI +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Граници, чувствителни към сигурността +## Security-Sensitive Boundaries -- JWT тайна (`JWT_SECRET`) защитава проверката/подписването на бисквитките на таблото за управление -- Първоначалната резервна парола (`INITIAL_PASSWORD`, по подразбиране `123456`) трябва да бъде заменена при реални внедрявания -- API ключ HMAC secret (`API_KEY_SECRET`) защитава генерирания локален формат на API ключ -- Тайните на доставчика (API ключове/токени) се съхраняват в локалната база данни и трябва да бъдат защитени на ниво файлова система -- Крайните точки за синхронизиране в облак разчитат на удостоверяване на API ключ + семантика на идентификатор на машина +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Околна среда и матрица за изпълнение +## Environment and Runtime Matrix -Променливите на средата, използвани активно от кода: +Environment variables actively used by code: -- Приложение/удостоверяване: `JWT_SECRET`, `INITIAL_PASSWORD` -- Съхранение: `DATA_DIR` -- Съвместимо поведение на възел: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Допълнителна отмяна на базата за съхранение (Linux/macOS, когато `DATA_DIR` не е зададен): `XDG_CONFIG_HOME` -- Хеширане на сигурността: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Регистриране: `ENABLE_REQUEST_LOGS` -- Синхронизиране/облачно URL адресиране: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Изходящ прокси: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` и варианти с малки букви -- Флагове за функция SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Помощници за платформа/време на изпълнение (не специфична за приложението конфигурация): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Известни архитектурни бележки +## Known Architectural Notes -1. `usageDb` и `localDb` сега споделят една и съща основна политика за директория (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) с мигриране на наследени файлове. -2. `/api/v1/route.ts` връща списък със статичен модел и не е основният източник на модели, използван от `/v1/models`. -3. Request logger записва пълни заглавки/тяло, когато е разрешено; третира регистрационната директория като чувствителна. -4. Поведението в облака зависи от правилния `NEXT_PUBLIC_BASE_URL` и достижимостта на крайната точка на облака. -5. Директорията `open-sse/` е публикувана като `@omniroute/open-sse` **npm workspace package**. Изходният код го импортира чрез `@omniroute/open-sse/...` (разрешено от Next.js `transpilePackages`). Пътищата на файловете в този документ все още използват името на директорията `open-sse/` за последователност. -6. Диаграмите в таблото за управление използват **Recharts** (базирани на SVG) за достъпни, интерактивни аналитични визуализации (стълбовидни диаграми на използването на модела, таблици с разбивка на доставчиците с проценти на успех). -7. E2E тестовете използват **Playwright** (`tests/e2e/`), изпълняват се чрез `npm run test:e2e`. Модулните тестове използват **Node.js test runner** (`tests/unit/`), изпълняват се чрез `npm run test:plan3`. Изходният код под `src/` е **TypeScript** (`.ts`/`.tsx`); работното пространство `open-sse/` остава JavaScript (`.js`). -8. Страницата с настройки е организирана в 5 раздела: Сигурност, Маршрутизиране (6 глобални стратегии: първо попълване, кръгъл-робин, p2c, произволна, най-малко използвана, оптимизирана по отношение на разходите), Устойчивост (ограничения на скоростта за редактиране, прекъсвач, политики), AI (мислещ бюджет, системна подкана, кеш за подкана), Разширени (прокси). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Контролен списък за оперативна проверка +## Operational Verification Checklist -- Създаване от източник: `npm run build` -- Изграждане на Docker изображение: `docker build -t omniroute .` -- Стартирайте услугата и проверете: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- CLI целеви базов URL трябва да бъде `http://:20128/v1`, когато `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/bg/CODEBASE_DOCUMENTATION.md b/docs/i18n/bg/CODEBASE_DOCUMENTATION.md index b49eb6498c..303880c198 100644 --- a/docs/i18n/bg/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/bg/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Документация на кодовата база +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Изчерпателно, удобно за начинаещи ръководство за **omniroute** прокси рутер с изкуствен интелект с множество доставчици. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Какво е omniroute? +## 1. What Is omniroute? -omniroute е **прокси рутер**, който се намира между AI клиенти (Claude CLI, Codex, Cursor IDE и др.) и AI доставчици (Anthropic, Google, OpenAI, AWS, GitHub и др.). Решава един голям проблем: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Различните AI клиенти говорят различни „езици“ (API формати) и различните доставчици на AI също очакват различни „езици“.** omniroute превежда автоматично между тях. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Мислете за това като за универсален преводач в Обединените нации - всеки делегат може да говори всеки език и преводачът го преобразува за всеки друг делегат. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Преглед на архитектурата +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Основен принцип: Превод на централно ниво +### Core Principle: Hub-and-Spoke Translation -Всички преводи на формати преминават през **OpenAI формат като център**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Това означава, че имате нужда само от **N преводачи** (по един на формат) вместо от **N²** (всяка двойка). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Структура на проекта +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Разбивка модул по модул +## 4. Module-by-Module Breakdown -### 4.1 Конфигурация (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**Единственият източник на истина** за всички конфигурации на доставчика. +The **single source of truth** for all provider configuration. -| Файл | Цел | -| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` обект с основни URL адреси, идентификационни данни за OAuth (по подразбиране), заглавки и системни подкани по подразбиране за всеки доставчик. Също така дефинира `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` и `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Зарежда външни идентификационни данни от `data/provider-credentials.json` и ги обединява върху твърдо кодираните настройки по подразбиране в `PROVIDERS`. Пази тайните извън контрола на източника, като същевременно поддържа обратна съвместимост. | -| `providerModels.ts` | Централен регистър на моделите: псевдоними на доставчика на карти → ID на модела. Функции като `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Системни инструкции, инжектирани в заявките на Codex (ограничения за редактиране, правила на пясъчника, правила за одобрение). | -| `defaultThinkingSignature.ts` | „Мислещи“ подписи по подразбиране за модели Claude и Gemini. | -| `ollamaModels.ts` | Дефиниция на схема за локални модели Ollama (име, размер, семейство, квантуване). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Поток на зареждане на идентификационни данни +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Изпълнители (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Изпълнителите капсулират **специфична за доставчика логика**, използвайки **стратегически модел**. Всеки изпълнител замества основните методи, ако е необходимо. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Изпълнител | Доставчик | Ключови специализации | -| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Абстрактна база: изграждане на URL, заглавки, логика за повторен опит, опресняване на идентификационни данни | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Генерично опресняване на OAuth токен за стандартни доставчици | -| `antigravity.ts` | Google Cloud Code | Генериране на идентификатор на проект/сесия, резервен URL адрес с множество URL адреси, персонализирано анализиране на повторен опит от съобщения за грешка („нулиране след 2h7m23s“) | -| `cursor.ts` | Курсор IDE | **Най-сложни**: SHA-256 контролна сума auth, Protobuf кодиране на заявка, двоичен EventStream → SSE отговор анализ | -| `codex.ts` | OpenAI Codex | Вкарва системни инструкции, управлява нивата на мислене, премахва неподдържаните параметри | -| `gemini-cli.ts` | Google Gemini CLI | Изграждане на персонализиран URL (`streamGenerateContent`), опресняване на Google OAuth токен | -| `github.ts` | Копилот на GitHub | Система с двоен токен (GitHub OAuth + Copilot token), имитиране на заглавката на VSCode | -| `kiro.ts` | AWS CodeWhisperer | Двоичен анализ на AWS EventStream, рамки за събития AMZN, оценка на токена | -| `index.ts` | — | Фабрика: картографира името на доставчика → клас изпълнител, с резервен вариант по подразбиране | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Манипулатори (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**Слоят за оркестрация** — координира превода, изпълнението, поточното предаване и обработката на грешки. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Файл | Цел | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Централен оркестратор** (~600 реда). Обработва пълния жизнен цикъл на заявката: откриване на формат → превод → изпращане на изпълнител → стрийминг/не-стрийминг отговор → опресняване на токена → обработка на грешки → регистриране на използването. | -| `responsesHandler.ts` | Адаптер за API за отговори на OpenAI: преобразува формата на отговорите → Завършвания на чат → изпраща до `chatCore` → конвертира SSE обратно във формат на отговорите. | -| `embeddings.ts` | Манипулатор за генериране на вграждане: разрешава модел на вграждане → доставчик, изпраща до API на доставчика, връща съвместим с OpenAI отговор за вграждане. Поддържа 6+ доставчици. | -| `imageGeneration.ts` | Манипулатор за генериране на изображения: разрешава модел на изображение → доставчик, поддържа режими, съвместими с OpenAI, Gemini-image (Антигравитация) и резервни (Nebius). Връща base64 или URL изображения. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Жизнен цикъл на заявка (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Услуги (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Бизнес логика, която поддържа манипулаторите и изпълнителите. +Business logic that supports the handlers and executors. -| Файл | Цел | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Откриване на формат** (`detectFormat`): анализира структурата на тялото на заявката, за да идентифицира форматите Claude/OpenAI/Gemini/Antigravity/Responses (включва `max_tokens` евристика за Claude). Също така: изграждане на URL адреси, изграждане на заглавки, нормализиране на конфигурацията на мислене. Поддържа `openai-compatible-*` и `anthropic-compatible-*` динамични доставчици. | -| `model.ts` | Разбор на низ на модел (`claude/model-name` → `{provider: "claude", model: "model-name"}`), разрешаване на псевдоними с откриване на сблъсък, дезинфекция на входа (отхвърля преминаване на пътя/контролни знаци) и разрешаване на информация за модела с поддръжка на асинхронно получаване на псевдоними. | -| `accountFallback.ts` | Обработка на ограничение на скоростта: експоненциално забавяне (1s → 2s → 4s → макс. 2min), управление на изчакване на акаунта, класификация на грешките (кои грешки задействат резервно или не). | -| `tokenRefresh.ts` | Опресняване на OAuth токена за **всеки доставчик**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Включва кеш за дедупликация на обещание по време на полет и повторен опит с експоненциално забавяне. | -| `combo.ts` | **Комбинирани модели**: вериги от резервни модели. Ако модел A се провали с допустима грешка за резервен вариант, опитайте модел B, след това C и т.н. Връща действителните кодове за състояние нагоре по веригата. | -| `usage.ts` | Извлича данни за квоти/използване от API на доставчика (квоти на GitHub Copilot, квоти на модела на Antigravity, ограничения на скоростта на Codex, разбивки на използването на Kiro, настройки на Claude). | -| `accountSelector.ts` | Интелигентен избор на акаунт с алгоритъм за точкуване: взема предвид приоритет, здравословно състояние, кръгова позиция и състояние на изчакване, за да избере оптималния акаунт за всяка заявка. | -| `contextManager.ts` | Управление на жизнения цикъл на контекста на заявката: създава и проследява контекстни обекти на заявка с метаданни (идентификатор на заявка, времеви клейма, информация за доставчика) за отстраняване на грешки и регистриране. | -| `ipFilter.ts` | IP-базиран контрол на достъпа: поддържа разрешени и блокирани режими. Валидира клиентския IP адрес спрямо конфигурирани правила, преди да обработи API заявки. | -| `sessionManager.ts` | Проследяване на сесии с пръстов отпечатък на клиента: проследява активни сесии с помощта на хеширани клиентски идентификатори, следи броя на заявките и предоставя показатели за сесиите. | -| `signatureCache.ts` | Кеш за дедупликация, базиран на подписи на заявки: предотвратява дублиране на заявки чрез кеширане на подписи на скорошни заявки и връщане на кеширани отговори за идентични заявки в рамките на времеви прозорец. | -| `systemPrompt.ts` | Инжектиране на глобална системна подкана: добавя пред или добавя конфигурируема системна подкана към всички заявки, с обработка на съвместимостта за всеки доставчик. | -| `thinkingBudget.ts` | Управление на бюджета на токените за разсъждение: поддържа режими за преминаване, автоматичен (конфигурация на лентово мислене), персонализиран (фиксиран бюджет) и адаптивен (мащабиран според сложността) режими за контролиране на токени за мислене/разсъждение. | -| `wildcardRouter.ts` | Маршрутизиране на модела със заместващи знаци: разрешава шаблони със заместващи знаци (напр. `*/claude-*`) до конкретни двойки доставчик/модел въз основа на наличност и приоритет. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Дедупликация на опресняване на токени +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Резервна държавна машина на акаунта +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Комбиниран модел верига +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Преводач (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**Машината за превод на формати**, използваща саморегистрираща се плъгин система. +The **format translation engine** using a self-registering plugin system. -#### Архитектура +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Указател | Файлове | Описание | -| ------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 преводачи | Преобразувайте тела на заявки между формати. Всеки файл се саморегистрира чрез `register(from, to, fn)` при импортиране. | -| `response/` | 7 преводачи | Преобразувайте поточно предавани отговори между формати. Обработва SSE типове събития, мисловни блокове, извиквания на инструменти. | -| `helpers/` | 6 помощника | Споделени помощни програми: `claudeHelper` (извличане на системни подкани, мислеща конфигурация), `geminiHelper` (съпоставяне на части/съдържание), `openaiHelper` (филтриране на формат), `toolCallHelper` (генериране на ID, инжектиране на липсващ отговор), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Механизъм за превод: `translateRequest()`, `translateResponse()`, управление на състоянието, регистър. | -| `formats.ts` | — | Константи на формата: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Ключов дизайн: Саморегистриращи се добавки +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,17 +395,17 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Помощни средства (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Файл | Цел | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `error.ts` | Изграждане на отговор при грешка (съвместим с OpenAI формат), анализиране на грешка нагоре по веригата, извличане на времето за повторен опит на Antigravity от съобщения за грешка, поточно предаване на грешка на SSE. | -| `stream.ts` | **SSE Transform Stream** — основният тръбопровод за стрийминг. Два режима: `TRANSLATE` (превод в пълен формат) и `PASSTHROUGH` (нормализиране + извличане на използването). Управлява буфериране на парчета, оценка на използването, проследяване на дължината на съдържанието. Екземплярите на енкодер/декодер на поток избягват споделено състояние. | -| `streamHelpers.ts` | Помощни програми за SSE на ниско ниво: `parseSSELine` (толерантни към бели интервали), `hasValuableContent` (филтрира празни парчета за OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (сериализация на SSE, съобразена с формата с `perf_metrics` почистване). | -| `usageTracking.ts` | Извличане на използване на токени от всеки формат (Claude/OpenAI/Gemini/Responses), оценка с отделни съотношения на инструмент/съобщение char-per-token, добавяне на буфер (марж за безопасност от 2000 токена), филтриране на специфично за формат поле, конзолно регистриране с ANSI цветове. | -| `requestLogger.ts` | Регистриране на искания на базата на файл (включване чрез `ENABLE_REQUEST_LOGS=true`). Създава сесийни папки с номерирани файлове: `1_req_client.json` → `7_res_client.txt`. Всички I/O са асинхронни (задействай и забрави). Маскира чувствителните заглавки. | -| `bypassHandler.ts` | Прихваща специфични модели от Claude CLI (извличане на заглавие, загряване, броене) и връща фалшиви отговори, без да се обажда на доставчик. Поддържа както стрийминг, така и не стрийминг. Умишлено ограничен до Claude CLI обхват. | -| `networkProxy.ts` | Разрешава URL адрес на изходящ прокси за даден доставчик с приоритет: специфична за доставчика конфигурация → глобална конфигурация → променливи на средата (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Поддържа `NO_PROXY` изключения. Кешира конфигурацията за 30s. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | #### SSE Streaming Pipeline @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Структура на сесията на регистратора на заявка +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Приложен слой (`src/`) +### 4.7 Application Layer (`src/`) -| Указател | Цел | -| ------------- | ------------------------------------------------------------------------------------------------------------ | -| `src/app/` | Уеб потребителски интерфейс, API маршрути, Express междинен софтуер, манипулатори за обратно извикване OAuth | -| `src/lib/` | Достъп до база данни (`localDb.ts`, `usageDb.ts`), удостоверяване, споделено | -| `src/mitm/` | Прокси помощни програми Man-in-the-middle за прихващане на трафик на доставчик | -| `src/models/` | Дефиниции на модел на база данни | -| `src/shared/` | Обвивки около open-sse функции (доставчик, поток, грешка и др.) | -| `src/sse/` | SSE манипулатори на крайни точки, които свързват библиотеката open-sse към експресни маршрути | -| `src/store/` | Управление на състоянието на приложението | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Известни API маршрути +#### Notable API Routes -| Маршрут | Методи | Цел | -| --------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | ПОЛУЧАВАНЕ/ПУБЛИКУВАНЕ/ИЗТРИВАНЕ | CRUD за потребителски модели на доставчик | -| `/api/models/catalog` | ВЗЕМЕТЕ | Обобщен каталог на всички модели (чат, вграждане, изображение, персонализирани), групирани по доставчик | -| `/api/settings/proxy` | ПОЛУЧАВАНЕ/ПОСТАВЯНЕ/ИЗТРИВАНЕ | Конфигурация на йерархичен изходящ прокси (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | ПУБЛИКАЦИЯ | Потвърждава прокси свързаността и връща публичен IP/латентност | -| `/v1/providers/[provider]/chat/completions` | ПУБЛИКАЦИЯ | Специализирани завършвания на чат за всеки доставчик с валидиране на модел | -| `/v1/providers/[provider]/embeddings` | ПУБЛИКАЦИЯ | Специализирани вграждания за всеки доставчик с валидиране на модел | -| `/v1/providers/[provider]/images/generations` | ПУБЛИКАЦИЯ | Специално генериране на изображения за всеки доставчик с валидиране на модел | -| `/api/settings/ip-filter` | ВЗЕМИ/ПОСТАВИ | Управление на списък с разрешени/блокирани IP | -| `/api/settings/thinking-budget` | ВЗЕМИ/ПОСТАВИ | Конфигурация на бюджета на токена за разсъждение (пропускане/автоматично/персонализирано/адаптивно) | -| `/api/settings/system-prompt` | ВЗЕМИ/ПОСТАВИ | Бързо инжектиране на глобална система за всички заявки | -| `/api/sessions` | ВЗЕМЕТЕ | Проследяване на активна сесия и показатели | -| `/api/rate-limits` | ВЗЕМЕТЕ | Състояние на ограничение на лимита по сметка | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Ключови модели на дизайн +## 5. Key Design Patterns -### 5.1 Hub-and-Spoke превод +### 5.1 Hub-and-Spoke Translation -Всички формати се превеждат през **OpenAI формат като център**. Добавянето на нов доставчик изисква само писане на **една двойка** преводачи (към/от OpenAI), а не на N двойки. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Модел на стратегия за изпълнител +### 5.2 Executor Strategy Pattern -Всеки доставчик има специален клас изпълнител, наследен от `BaseExecutor`. Фабриката в `executors/index.ts` избира правилния по време на изпълнение. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Саморегистрираща се плъгин система +### 5.3 Self-Registering Plugin System -Модулите за преводач се регистрират при импортиране чрез `register()`. Добавянето на нов преводач е просто създаване на файл и импортирането му. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Резервен акаунт с експоненциално отстъпление +### 5.4 Account Fallback with Exponential Backoff -Когато доставчикът върне 429/401/500, системата може да превключи към следващия акаунт, прилагайки експоненциално охлаждане (1s → 2s → 4s → max 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### Комбинирани вериги за модели 5.5 +### 5.5 Combo Model Chains -„Комбо“ групира множество низове `provider/model`. Ако първият не успее, автоматично се върнете към следващия. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Поточен превод с пълно състояние +### 5.6 Stateful Streaming Translation -Преводът на отговор поддържа състоянието в SSE блокове (проследяване на мислещ блок, натрупване на извикване на инструмент, индексиране на блок съдържание) чрез механизма `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Буфер за безопасност при използване +### 5.7 Usage Safety Buffer -Добавя се буфер от 2000 токена към отчетеното използване, за да се предотврати достигането на ограниченията на контекстните прозорци на клиентите поради натоварване от системни подкани и превод на формати. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Поддържани формати +## 6. Supported Formats -| Формат | Посока | Идентификатор | -| ------------------------- | -------------- | ------------------ | -| Завършвания на OpenAI чат | източник + цел | `openai` | -| OpenAI Responses API | източник + цел | `openai-responses` | -| Антропичен Клод | източник + цел | `claude` | -| Google Gemini | източник + цел | `gemini` | -| Google Gemini CLI | само цел | `gemini-cli` | -| Антигравитация | източник + цел | `antigravity` | -| AWS Киро | само цел | `kiro` | -| Курсор | само цел | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Поддържани доставчици +## 7. Supported Providers -| Доставчик | Метод за удостоверяване | Изпълнител | Основни бележки | -| ------------------------ | -------------------------------- | --------------- | -------------------------------------------------- | -| Антропичен Клод | API ключ или OAuth | По подразбиране | Използва `x-api-key` заглавка | -| Google Gemini | API ключ или OAuth | По подразбиране | Използва `x-goog-api-key` заглавка | -| Google Gemini CLI | OAuth | GeminiCLI | Използва `streamGenerateContent` крайна точка | -| Антигравитация | OAuth | Антигравитация | Multi-URL резервен, персонализиран повторен анализ | -| OpenAI | API ключ | По подразбиране | Удостоверяване на стандартен носител | -| Кодекс | OAuth | Кодекс | Инжектира системни инструкции, управлява мисленето | -| Копилот на GitHub | OAuth + Copilot token | Github | Двоен токен, имитираща заглавка на VSCode | -| Киро (AWS) | AWS SSO OIDC или социални | Киро | Парсинг на двоичен EventStream | -| Курсор IDE | Контролна сума за удостоверяване | Курсор | Protobuf кодиране, SHA-256 контролни суми | -| Куен | OAuth | По подразбиране | Стандартно удостоверяване | -| iFlow | OAuth (основен + носител) | По подразбиране | Заглавка за двойно удостоверяване | -| OpenRouter | API ключ | По подразбиране | Удостоверяване на стандартен носител | -| GLM, Kimi, MiniMax | API ключ | По подразбиране | Съвместим с Claude, използвайте `x-api-key` | -| `openai-compatible-*` | API ключ | По подразбиране | Динамично: всяка крайна точка, съвместима с OpenAI | -| `anthropic-compatible-*` | API ключ | По подразбиране | Динамично: всяка крайна точка, съвместима с Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Резюме на потока от данни +## 8. Data Flow Summary -### Заявка за поточно предаване +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Заявка без поточно предаване +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Байпасен поток (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/bg/FEATURES.md b/docs/i18n/bg/FEATURES.md index cf349495af..82cc73b67b 100644 --- a/docs/i18n/bg/FEATURES.md +++ b/docs/i18n/bg/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Галерия с функции на таблото +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Визуално ръководство за всеки раздел на таблото за управление OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Доставчици +## 🔌 Providers -Управлявайте връзките на доставчици на AI: OAuth доставчици (Claude Code, Codex, Gemini CLI), доставчици на API ключове (Groq, DeepSeek, OpenRouter) и безплатни доставчици (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Комбота +## 🎨 Combos -Създавайте комбинации за маршрутизиране на модели с 6 стратегии: първо попълване, кръгъл робин, мощност от два избора, произволна, най-малко използвана и оптимизирана по отношение на разходите. Всяка комбинация свързва няколко модела с автоматичен резервен вариант. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Анализ +## 📊 Analytics -Изчерпателни анализи на използването с потребление на токени, оценки на разходите, топлинни карти на активността, седмични диаграми на разпределение и разбивки по доставчик. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Здраве на системата +## 🏥 System Health -Мониторинг в реално време: време на работа, памет, версия, процентили на латентност (p50/p95/p99), статистика на кеша и състояния на прекъсвача на доставчика. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Площадка за преводачи +## 🔧 Translator Playground -Четири режима за отстраняване на грешки в API преводи: **Playground** (конвертор на формати), **Chat Tester** (заявки на живо), **Test Bench** (пакетни тестове) и **Live Monitor** (поток в реално време). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Настройки +## 🎮 Model Playground _(v2.0.9+)_ -Общи настройки, системно съхранение, управление на архивиране (база данни за експортиране/импортиране), външен вид (тъмен/светъл режим), сигурност (включва защита на крайна точка на API и блокиране на потребителски доставчик), маршрутизиране, устойчивост и разширена конфигурация. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI инструменти +## 🔧 CLI Tools -Конфигурация с едно щракване за инструменти за кодиране на AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code и Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Регистри за заявки +## 🤖 CLI Agents _(v2.0.11+)_ -Регистриране на заявки в реално време с филтриране по доставчик, модел, акаунт и API ключ. Показва кодове за състояние, използване на токени, латентност и подробности за отговора. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Крайна точка на API +## 🌐 API Endpoint -Вашата унифицирана крайна точка на API с разбивка на възможностите: завършвания на чат, вграждания, генериране на изображения, прекласиране, аудио транскрипция и регистрирани ключове за API. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/bg/TROUBLESHOOTING.md b/docs/i18n/bg/TROUBLESHOOTING.md index 3883a28309..120092d63c 100644 --- a/docs/i18n/bg/TROUBLESHOOTING.md +++ b/docs/i18n/bg/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Отстраняване на неизправности +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Често срещани проблеми и решения за OmniRoute. +Common problems and solutions for OmniRoute. --- -## Бързи поправки +## Quick Fixes -| Проблем | Решение | -| ------------------------------------------------- | ------------------------------------------------------------------------------ | -| Първото влизане не работи | Проверете `INITIAL_PASSWORD` в `.env` (по подразбиране: `123456`) | -| Таблото се отваря на грешен порт | Задайте `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Няма регистрационни файлове за заявки под `logs/` | Задайте `ENABLE_REQUEST_LOGS=true` | -| EACCES: разрешението е отказано | Задайте `DATA_DIR=/path/to/writable/dir` да замени `~/.omniroute` | -| Стратегията за маршрутизиране не се запазва | Актуализация до v1.4.11+ (корекция на Zod схема за постоянство на настройките) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Проблеми с доставчика +## Provider Issues -### „Езиковият модел не предостави съобщения“ +### "Language model did not provide messages" -**Причина:** Квотата на доставчика е изчерпана. +**Cause:** Provider quota exhausted. -**Коригиране:** +**Fix:** -1. Проверете инструмента за проследяване на квоти на таблото за управление -2. Използвайте комбо с резервни нива -3. Преминете към по-евтино/безплатно ниво +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Ограничаване на скоростта +### Rate Limiting -**Причина:** Абонаментната квота е изчерпана. +**Cause:** Subscription quota exhausted. -**Коригиране:** +**Fix:** -- Добавете резервен вариант: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Използвайте GLM/MiniMax като евтино резервно копие +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth Token е изтекъл +### OAuth Token Expired -OmniRoute автоматично опреснява токените. Ако проблемите продължават: +OmniRoute auto-refreshes tokens. If issues persist: -1. Табло → Доставчик → Свързване отново -2. Изтрийте и добавете отново връзката с доставчика +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Проблеми с облака +## Cloud Issues -### Грешки при синхронизиране в облак +### Cloud Sync Errors -1. Проверете дали `BASE_URL` сочи към вашия работещ екземпляр (напр. `http://localhost:20128`) -2. Проверете `CLOUD_URL` точки към вашата крайна точка в облака (напр. `https://omniroute.dev`) -3. Поддържайте стойностите на `NEXT_PUBLIC_*` в съответствие със стойностите от страна на сървъра +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Връща 500 +### Cloud `stream=false` Returns 500 -**Симптом:** `Unexpected token 'd'...` в крайна точка на облака за обаждания без поточно предаване. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Причина:** Upstream връща SSE полезен товар, докато клиентът очаква JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Заобиколно решение:** Използвайте `stream=true` за директни обаждания в облака. Локалното време на изпълнение включва резервен SSE→JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Облакът казва Свързан, но „Невалиден API ключ“ +### Cloud Says Connected but "Invalid API key" -1. Създайте нов ключ от локалното табло за управление (`/api/keys`) -2. Стартирайте облачна синхронизация: Активирайте Облак → Синхронизирай сега -3. Старите/несинхронизирани ключове все още могат да връщат `401` в облака +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Проблеми с Docker +## Docker Issues -### CLI инструментът показва, че не е инсталиран +### CLI Tool Shows Not Installed -1. Проверете полетата по време на изпълнение: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. За преносим режим: използвайте целево изображение `runner-cli` (пакетни CLI) -3. За режим на монтиране на хост: задайте `CLI_EXTRA_PATHS` и монтирайте директорията bin на хоста като само за четене -4. Ако `installed=true` и `runnable=false`: двоичен файл е намерен, но проверката на състоянието е неуспешна +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Бързо валидиране по време на изпълнение +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Проблеми с разходите +## Cost Issues -### Високи разходи +### High Costs -1. Проверете статистическите данни за употреба в Табло → Използване -2. Превключете основния модел на GLM/MiniMax -3. Използвайте безплатно ниво (Gemini CLI, iFlow) за некритични задачи -4. Задайте бюджети за разходи за API ключ: Табло за управление → API ключове → Бюджет +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Отстраняване на грешки +## Debugging -### Активиране на регистрационните файлове на заявките +### Enable Request Logs -Задайте `ENABLE_REQUEST_LOGS=true` във вашия `.env` файл. Дневниците се появяват в директорията `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Проверете здравето на доставчика +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Съхранение по време на изпълнение +### Runtime Storage -- Основно състояние: `${DATA_DIR}/db.json` (доставчици, комбинации, псевдоними, ключове, настройки) -- Използване: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Регистрации за заявки: `/logs/...` (когато `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Проблеми с прекъсвача +## Circuit Breaker Issues -### Доставчикът остана в ОТВОРЕНО състояние +### Provider stuck in OPEN state -Когато прекъсвачът на доставчика е ОТВОРЕЕН, заявките се блокират, докато изтече времето за охлаждане. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Коригиране:** +**Fix:** -1. Отидете на **Табло → Настройки → Устойчивост** -2. Проверете картата на прекъсвача на засегнатия доставчик -3. Щракнете върху **Нулиране на всички**, за да изчистите всички прекъсвачи, или изчакайте времето за охлаждане да изтече -4. Уверете се, че доставчикът действително е наличен, преди да нулирате +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Доставчикът продължава да изключва прекъсвача +### Provider keeps tripping the circuit breaker -Ако доставчик многократно влиза в ОТВОРЕНО състояние: +If a provider repeatedly enters OPEN state: -1. Проверете **Табло → Здраве → Здраве на доставчика** за модела на повреда -2. Отидете на **Настройки → Устойчивост → Профили на доставчици** и увеличете прага на отказ -3. Проверете дали доставчикът е променил ограниченията на API или изисква повторно удостоверяване -4. Прегледайте телеметрията за латентност — високата латентност може да причини грешки, базирани на изчакване +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Проблеми с аудио транскрипцията +## Audio Transcription Issues -### Грешка „Неподдържан модел“. +### "Unsupported model" error -- Уверете се, че използвате правилния префикс: `deepgram/nova-3` или `assemblyai/best` -- Проверете дали доставчикът е свързан в **Табло → Доставчици** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Транскрипцията се връща празна или е неуспешна +### Transcription returns empty or fails -- Проверете поддържаните аудио формати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Уверете се, че размерът на файла е в границите на доставчика (обикновено < 25MB) -- Проверете валидността на API ключа на доставчика в картата на доставчика +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Отстраняване на грешки на преводача +## Translator Debugging -Използвайте **Табло за управление → Преводач** за отстраняване на грешки при проблеми с превода на формат: +Use **Dashboard → Translator** to debug format translation issues: -| Режим | Кога да използвате | -| ------------------- | --------------------------------------------------------------------------------------------------------- | -| **Детска площадка** | Сравнете входно/изходните формати един до друг — поставете неуспешна заявка, за да видите как се превежда | -| **Чат тестер** | Изпращайте съобщения на живо и проверявайте пълния полезен товар на заявка/отговор, включително заглавки | -| **Тестова стенда** | Изпълнете пакетни тестове в комбинации от формати, за да откриете кои преводи са нарушени | -| **Монитор на живо** | Гледайте потока на заявките в реално време, за да уловите периодични проблеми с превода | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Често срещани проблеми с формата +### Common format issues -- **Мислещите етикети не се появяват** — Проверете дали целевият доставчик поддържа мисленето и настройката на бюджета за мислене -- **Отпадане на извикванията на инструменти** — Някои преводи на формати може да премахнат неподдържаните полета; потвърдете в режим Playground -- **Липсва системна подкана** — Клод и Джемини обработват системните подкани по различен начин; проверка на резултата за превод -- **SDK връща необработен низ вместо обект** — Коригирано във v1.1.0: дезинфекциращото средство за отговор вече премахва нестандартните полета (`x_groq`, `usage_breakdown` и т.н.), които причиняват неуспешно валидиране на OpenAI SDK Pydantic -- **GLM/ERNIE отхвърля `system` роля** — Коригирано във v1.1.0: нормализаторът на роли автоматично обединява системни съобщения в потребителски съобщения за несъвместими модели -- **`developer` ролята не е разпозната** — Коригирано във v1.1.0: автоматично преобразувано в `system` за доставчици, които не са OpenAI -- **`json_schema` не работи с Gemini** — Коригирано във v1.1.0: `response_format` сега се преобразува в `responseMimeType` + `responseSchema` на Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Настройки за устойчивост +## Resilience Settings -### Автоматичното ограничение на скоростта не се задейства +### Auto rate-limit not triggering -- Автоматичното ограничение на скоростта се прилага само за доставчици на API ключове (не OAuth/абонамент) -- Уверете се, че **Настройки → Устойчивост → Профили на доставчици** има активиран автоматичен лимит на скоростта -- Проверете дали доставчикът връща `429` кодове за състояние или `Retry-After` заглавки +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Настройване на експоненциално забавяне +### Tuning exponential backoff -Профилите на доставчика поддържат тези настройки: +Provider profiles support these settings: -- **Базово забавяне** — Първоначално време на изчакване след първата повреда (по подразбиране: 1s) -- **Максимално забавяне** — Максимално ограничение на времето за изчакване (по подразбиране: 30 секунди) -- **Множител** — Колко да се увеличи закъснението за последователен отказ (по подразбиране: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Анти-гръмотевично стадо +### Anti-thundering herd -Когато много едновременни заявки попаднат на доставчик с ограничена скорост, OmniRoute използва mutex + автоматично ограничаване на скоростта, за да сериализира заявките и да предотврати каскадни грешки. Това е автоматично за доставчиците на API ключове. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Все още сте заседнали? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Проблеми с GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Архитектура**: Вижте [link](ARCHITECTURE.md) за вътрешни подробности -- **API Reference**: Вижте [link](API_REFERENCE.md) за всички крайни точки -- **Табло за управление на здравето**: Проверете **Табло за управление → Здраве** за състоянието на системата в реално време -- **Преводач**: Използвайте **Табло за управление → Преводач** за отстраняване на грешки при проблеми с формата +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/bg/USER_GUIDE.md b/docs/i18n/bg/USER_GUIDE.md index 38e4d07f36..5a043224df 100644 --- a/docs/i18n/bg/USER_GUIDE.md +++ b/docs/i18n/bg/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Ръководство за потребителя +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Пълно ръководство за конфигуриране на доставчици, създаване на комбинации, интегриране на CLI инструменти и внедряване на OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Съдържание +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 Ценообразуването с един поглед +## 💰 Pricing at a Glance -| Ниво | Доставчик | Цена | Нулиране на квота | Най-добро за | -| ------------------ | ----------------- | --------------------- | ----------------------- | ------------------------- | -| **💳 АБОНАМЕНТ** | Claude Code (Pro) | $20/месец | 5 часа + седмично | Вече сте абонирани | -| | Codex (Plus/Pro) | $20-200/месец | 5 часа + седмично | Потребители на OpenAI | -| | Gemini CLI | **БЕЗПЛАТНО** | 180K/месец + 1K/ден | всички! | -| | Копилот на GitHub | $10-19/месец | Месечно | Потребители на GitHub | -| **🔑 КЛЮЧ ЗА API** | DeepSeek | Плащане за използване | Няма | Евтини разсъждения | -| | Groq | Плащане за използване | Няма | Свръхбърз извод | -| | xAI (Grok) | Плащане за използване | Няма | Грок 4 разсъждения | -| | Мистрал | Плащане за използване | Няма | Хоствани в ЕС модели | -| | Недоумение | Плащане за използване | Няма | Разширено търсене | -| | Заедно AI | Плащане за използване | Няма | Модели с отворен код | -| | Фойерверки AI | Плащане за използване | Няма | Бързи FLUX изображения | -| | Мозъци | Плащане за използване | Няма | Скорост на вафла | -| | Cohere | Плащане за използване | Няма | Команда R+ RAG | -| | NVIDIA NIM | Плащане за използване | Няма | Корпоративни модели | -| **💰 ЕВТИНО** | GLM-4.7 | $0,6/1 милион | Ежедневно 10 сутринта | Резервно копие на бюджета | -| | MiniMax M2.1 | $0,2/1 милион | 5-часово търкаляне | Най-евтиният вариант | -| | Кими К2 | $9/месец апартамент | 10 милиона токена/месец | Предвидими разходи | -| **🆓 БЕЗПЛАТНО** | iFlow | $0 | Неограничен | 8 модела безплатно | -| | Куен | $0 | Неограничен | 3 модела безплатно | -| | Киро | $0 | Неограничен | Клод безплатно | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Професионален съвет:** Започнете с Gemini CLI (180K безплатно/месец) + iFlow (неограничено безплатно) комбинация = $0 цена! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Случаи на употреба +## 🎯 Use Cases -### Случай 1: „Имам абонамент за Claude Pro“ +### Case 1: "I have Claude Pro subscription" -**Проблем:** Квотата изтича неизползвана, ограничения на скоростта по време на тежко кодиране +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Случай 2: „Искам нулеви разходи“ +### Case 2: "I want zero cost" -**Проблем:** Не мога да си позволя абонаменти, имам нужда от надеждно AI кодиране +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Случай 3: „Имам нужда от кодиране 24/7, без прекъсвания“ +### Case 3: "I need 24/7 coding, no interruptions" -**Проблем:** Крайни срокове, не мога да си позволя престой +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Случай 4: „Искам БЕЗПЛАТЕН AI в OpenClaw“ +### Case 4: "I want FREE AI in OpenClaw" -**Проблем:** Имате нужда от AI асистент в приложенията за съобщения, напълно безплатно +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Настройка на доставчик +## 📖 Provider Setup -### 🔐 Доставчици на абонаменти +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Професионален съвет:** Използвайте Opus за сложни задачи, Sonnet за скорост. OmniRoute проследява квота за модел! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (БЕЗПЛАТНО 180K/месец!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Най-добра стойност:** Огромно безплатно ниво! Използвайте това преди платените нива. +**Best Value:** Huge free tier! Use this before paid tiers. -#### Копилот на GitHub +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Евтини доставчици +### 💰 Cheap Providers -#### GLM-4.7 (Ежедневно нулиране, $0,6/1 млн.) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Регистрирайте се: [Zhipu AI](https://open.bigmodel.cn/) -2. Вземете API ключ от Coding Plan -3. Табло → Добавяне на API ключ: Доставчик: `glm`, API ключ: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Използване:** `glm/glm-4.7` — **Професионален съвет:** Планът за кодиране предлага 3× квота на цена 1/7! Нулирайте всеки ден в 10:00 ч. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 часа нулиране, $0,20/1 млн.) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Регистрирайте се: [MiniMax](https://www.minimax.io/) -2. Вземете API ключ → Табло → Добавете API ключ +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Използване:** `minimax/MiniMax-M2.1` — **Професионален съвет:** Най-евтината опция за дълъг контекст (1M токени)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/месец фиксиран) +#### Kimi K2 ($9/month flat) -1. Абонирайте се: [Moonshot AI](https://platform.moonshot.ai/) -2. Вземете API ключ → Табло → Добавете API ключ +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Използване:** `kimi/kimi-latest` — **Професионален съвет:** Фиксирани $9/месец за 10 милиона токена = $0,90/1 милион ефективна цена! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 БЕЗПЛАТНИ доставчици +### 🆓 FREE Providers -#### iFlow (8 БЕЗПЛАТНИ модела) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 БЕЗПЛАТНИ модела) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Киро (Клод БЕЗПЛАТНО) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Комбота +## 🎨 Combos -### Пример 1: Увеличаване на абонамента → Евтино архивиране +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Пример 2: Само безплатно (нулева цена) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI интеграция +## 🔧 CLI Integration -### Курсор IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Клод Код +### Claude Code -Редактиране на `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Редактиране на `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ codex "your prompt" } ``` -**Или използвайте таблото за управление:** CLI инструменти → OpenClaw → Автоматично конфигуриране +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Продължи / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Внедряване +## 🚀 Deployment -### Внедряване на VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### Докер +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -За интегриран в хост режим с двоични файлове на CLI вижте раздела Docker в основните документи. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Променливи на средата +### Environment Variables -| Променлива | По подразбиране | Описание | -| --------------------- | -------------------------------------- | ---------------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Тайна за подписване на JWT (**промяна в производството**) | -| `INITIAL_PASSWORD` | `123456` | Първа парола за влизане | -| `DATA_DIR` | `~/.omniroute` | Директория с данни (db, използване, регистрационни файлове) | -| `PORT` | рамка по подразбиране | Сервизен порт (`20128` в примерите) | -| `HOSTNAME` | рамка по подразбиране | Свързване на хост (Docker по подразбиране е `0.0.0.0`) | -| `NODE_ENV` | по подразбиране по време на изпълнение | Задайте `production` за внедряване | -| `BASE_URL` | `http://localhost:20128` | Вътрешен основен URL адрес от страната на сървъра | -| `CLOUD_URL` | `https://omniroute.dev` | Основен URL адрес на крайна точка за синхронизиране в облак | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC тайна за генерирани API ключове | -| `REQUIRE_API_KEY` | `false` | Прилагане на API ключ на носител на `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Разрешава регистрационни файлове за заявки/отговори | -| `AUTH_COOKIE_SECURE` | `false` | Принудително `Secure` бисквитка за удостоверяване (зад HTTPS обратен прокси) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -За пълната справка за променливите на средата вижте [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Налични модели +## 📊 Available Models
-Вижте всички налични модели +View all available models **Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — БЕЗПЛАТНО: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — $0,6/1 млн.: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $0,2/1 млн.: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — БЕЗПЛАТНО: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — БЕЗПЛАТНО: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Киро (`kr/`)** — БЕЗПЛАТНО: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -399,13 +458,13 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat **xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**Мистрал (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Недоумение (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Заедно AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Фойерверки AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` **Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` @@ -417,11 +476,11 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat --- -## 🧩 Разширени функции +## 🧩 Advanced Features -### Персонализирани модели +### Custom Models -Добавете всеки ID на модел към всеки доставчик, без да чакате актуализация на приложението: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Или използвайте таблото за управление: **Доставчици → [Доставчик] → Персонализирани модели**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Специализирани маршрути на доставчик +### Dedicated Provider Routes -Насочвайте заявките директно към конкретен доставчик с валидиране на модела: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Префиксът на доставчика се добавя автоматично, ако липсва. Несъответстващите модели връщат `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Конфигурация на мрежов прокси +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Приоритет:** Специфичен за ключ → Специфичен за комбинация → Специфичен за доставчик → Глобален → Среда. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API за каталог на модели +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Връща модели, групирани по доставчик с типове (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Облачно синхронизиране +### Cloud Sync -- Синхронизиране на доставчици, комбинации и настройки на всички устройства -- Автоматична фонова синхронизация с изчакване + бързо отказване -- Предпочитане на сървъра `BASE_URL`/`CLOUD_URL` в производството +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (Фаза 9) +### LLM Gateway Intelligence (Phase 9) -- **Семантичен кеш** — Автоматично кешира нестрийминг, температура=0 отговори (заобикаляне с `X-OmniRoute-No-Cache: true`) -- **Request Idempotency** — Дедупликира заявките в рамките на 5s чрез `Idempotency-Key` или `X-Request-Id` заглавка -- **Проследяване на напредъка** — Включване на SSE `event: progress` събития чрез `X-OmniRoute-Progress: true` заглавка +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Площадка за преводачи +### Translator Playground -Достъп чрез **Табло → Преводач**. Отстранете грешки и визуализирайте как OmniRoute превежда API заявки между доставчици. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Режим | Цел | -| ------------------- | ---------------------------------------------------------------------------------------------------- | -| **Детска площадка** | Изберете изходни/целеви формати, поставете заявка и незабавно вижте преведения резултат | -| **Чат тестер** | Изпращайте чат съобщения на живо през проксито и проверявайте пълния цикъл на заявка/отговор | -| **Тестова стенда** | Изпълнете групови тестове в множество комбинации от формати, за да проверите правилността на превода | -| **Монитор на живо** | Гледайте преводи в реално време, докато заявките преминават през проксито | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Случаи на употреба:** +**Use cases:** -- Отстраняване на грешки защо конкретна комбинация клиент/доставчик е неуспешна -- Проверете дали мислещите тагове, извикванията на инструменти и системните подкани се превеждат правилно -- Сравнете разликите във форматите между форматите OpenAI, Claude, Gemini и Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Стратегии за маршрутизиране +### Routing Strategies -Конфигурирайте чрез **Табло → Настройки → Маршрутизация**. +Configure via **Dashboard → Settings → Routing**. -| Стратегия | Описание | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------- | -| **Първо попълване** | Използва акаунти в приоритетен ред — основният акаунт обработва всички заявки, докато стане недостъпен | -| **Round Robin** | Преминава през всички акаунти с конфигурируем лепкав лимит (по подразбиране: 3 обаждания на акаунт) | -| **P2C (Сила на два избора)** | Избира 2 произволни акаунта и маршрути към по-здравословния — балансира натоварването с осъзнаване на здравето | -| **Произволно** | Произволно избира акаунт за всяка заявка чрез разбъркване на Fisher-Yates | -| **Най-малко използвани** | Насочва към акаунта с най-стария `lastUsedAt` времеви печат, разпределяйки трафика равномерно | -| **Оптимизирани разходи** | Маршрути към акаунта с най-ниска стойност на приоритет, оптимизиране за доставчици с най-ниска цена | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Псевдоними на модели със заместващи символи +#### Wildcard Model Aliases -Създайте шаблони със заместващи знаци, за да пренасочите имената на моделите: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Заместващите знаци поддържат `*` (всякакви знаци) и `?` (единичен знак). +Wildcards support `*` (any characters) and `?` (single character). -#### Резервни вериги +#### Fallback Chains -Дефинирайте глобални резервни вериги, които се прилагат за всички заявки: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Устойчивост и прекъсвачи +### Resilience & Circuit Breakers -Конфигурирайте чрез **Табло → Настройки → Устойчивост**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute прилага устойчивост на ниво доставчик с четири компонента: +OmniRoute implements provider-level resilience with four components: -1. **Профили на доставчици** — Конфигурация за всеки доставчик за: - - Праг на повреда (колко повреда преди отваряне) - - Продължителност на изчакване - - Чувствителност на откриване на ограничение на скоростта - - Параметри на експоненциално забавяне +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Редактируеми ограничения на скоростта** — Настройки по подразбиране на системно ниво, които могат да се конфигурират в таблото за управление: - - **Заявки в минута (RPM)** — Максимален брой заявки в минута за акаунт - - **Минимално време между заявките** — Минимална разлика в милисекунди между заявките - - **Максимални едновременни заявки** — Максимални едновременни заявки за акаунт - - Щракнете върху **Редактиране**, за да промените, след това върху **Запазване** или **Отказ**. Стойностите се запазват чрез API за устойчивост. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Прекъсвач на веригата** — Проследява повреди на доставчик и автоматично отваря веригата при достигане на праг: - - **ЗАТВОРЕНО** (здравословно) — Заявките протичат нормално - - **OPEN** — Доставчикът е временно блокиран след повтарящи се повреди - - **HALF_OPEN** — Тестване дали доставчикът се е възстановил +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Правила и заключени идентификатори** — Показва състоянието на прекъсвача и заключените идентификатори с възможност за принудително отключване. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Автоматично откриване на ограничение на скоростта** — Наблюдава заглавките `429` и `Retry-After`, за да избегне проактивно достигане на ограниченията на скоростта на доставчика. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Професионален съвет:** Използвайте бутона **Нулиране на всички**, за да изчистите всички прекъсвачи и изчаквания, когато доставчикът се възстанови от прекъсване. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Експорт/импорт на база данни +### Database Export / Import -Управлявайте резервни копия на бази данни в **Табло → Настройки → Система и съхранение**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Действие | Описание | -| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Експортиране на база данни** | Изтегля текущата база данни SQLite като `.sqlite` файл | -| **Експортиране на всички (.tar.gz)** | Изтегля пълен резервен архив, включително: база данни, настройки, комбинации, връзки с доставчик (без идентификационни данни), API ключ метаданни | -| **Импортиране на база данни** | Качете файл `.sqlite`, за да замените текущата база данни. Автоматично се създава резервно копие преди импортиране | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Проверка на импортиране:** Импортираният файл се валидира за цялост (проверка на SQLite pragma), необходими таблици (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) и размер (макс. 100MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Случаи на употреба:** +**Use Cases:** -- Мигрирайте OmniRoute между машини -- Създаване на външни резервни копия за възстановяване след бедствие -- Споделяне на конфигурации между членовете на екипа (експортиране на всички → споделяне на архив) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Табло за управление на настройките +### Settings Dashboard -Страницата с настройки е организирана в 5 раздела за лесна навигация: +The settings page is organized into 5 tabs for easy navigation: -| Раздел | Съдържание | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Сигурност** | Настройки за вход/парола, IP контрол на достъпа, API удостоверяване за `/models` и блокиране на доставчик | -| **Маршрутизиране** | Стратегия за глобално маршрутизиране (6 опции), псевдоними на модели със заместващи символи, резервни вериги, комбинирани настройки по подразбиране | -| **Устойчивост** | Профили на доставчици, редактируеми лимити на скоростта, състояние на прекъсвача, политики и заключени идентификатори | -| **AI** | Обмисляне на конфигурация на бюджета, инжектиране на глобална система, статистика на бързия кеш | -| **Разширено** | Глобална прокси конфигурация (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Управление на разходите и бюджета +### Costs & Budget Management -Достъп чрез **Табло → Разходи**. +Access via **Dashboard → Costs**. -| Раздел | Цел | -| ---------- | -------------------------------------------------------------------------------------------------------------- | -| **Бюджет** | Задайте лимити на разходите за API ключ с дневни/седмични/месечни бюджети и проследяване в реално време | -| **Цени** | Преглеждайте и редактирайте записи за ценообразуване на модела — цена за 1K входно/изходни токени на доставчик | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Проследяване на разходите:** Всяка заявка регистрира използването на токени и изчислява разходите с помощта на таблицата с цените. Вижте разбивки в **Табло за управление → Използване** по доставчик, модел и API ключ. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Аудио транскрипция +### Audio Transcription -OmniRoute поддържа аудио транскрипция чрез OpenAI-съвместима крайна точка: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Налични доставчици: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Поддържани аудио формати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Комбинирани стратегии за балансиране +### Combo Balancing Strategies -Конфигурирайте балансирането за комбо в **Табло за управление → Комбота → Създаване/Редактиране → Стратегия**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Стратегия | Описание | -| ---------------------------- | -------------------------------------------------------------------------------- | -| **Round-Robin** | Върти се през моделите последователно | -| **Приоритет** | Винаги пробва първия модел; връща се само при грешка | -| **Произволно** | Избира произволен модел от комбинацията за всяка заявка | -| **Претеглено** | Маршрути пропорционално въз основа на зададени тегла за модел | -| **Най-малко използвани** | Насочва към модела с най-малко скорошни заявки (използва комбинирани показатели) | -| **Оптимизиран за разходите** | Маршрути до най-евтиния наличен модел (използва ценова таблица) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Глобалните настройки по подразбиране на комбинацията могат да бъдат зададени в **Табло → Настройки → Маршрут → Настройки по подразбиране на комбинация**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Здравно табло +### Health Dashboard -Достъп чрез **Табло → Здраве**. Преглед на здравето на системата в реално време с 6 карти: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Карта | Какво показва | -| ---------------------------- | -------------------------------------------------------------------------- | -| **Състояние на системата** | Време на работа, версия, използване на паметта, директория с данни | -| **Здраве на доставчика** | Състояние на прекъсвача за всеки доставчик (затворен/отворен/полуотворен) | -| **Ограничения на скоростта** | Активен лимит на изчакване за акаунт с оставащо време | -| **Активни блокировки** | Доставчици, временно блокирани от политиката за блокиране | -| **Кеш на подписа** | Статистика на кеша за дедупликация (активни ключове, процент на попадения) | -| **Телеметрия за забавяне** | p50/p95/p99 агрегиране на латентност за доставчик | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Професионален съвет:** Страницата Health се опреснява автоматично на всеки 10 секунди. Използвайте картата на прекъсвача, за да идентифицирате кои доставчици имат проблеми. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/da/API_REFERENCE.md b/docs/i18n/da/API_REFERENCE.md index 509b50b2fc..b795722c11 100644 --- a/docs/i18n/da/API_REFERENCE.md +++ b/docs/i18n/da/API_REFERENCE.md @@ -1,12 +1,12 @@ -# API-reference +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Komplet reference for alle OmniRoute API-slutpunkter. +Complete reference for all OmniRoute API endpoints. --- -## Indholdsfortegnelse +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Komplet reference for alle OmniRoute API-slutpunkter. --- -## Chatafslutninger +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Brugerdefinerede overskrifter +### Custom Headers -| Overskrift | Retning | Beskrivelse | -| ------------------------ | --------- | ---------------------------------------------- | -| `X-OmniRoute-No-Cache` | Anmodning | Indstil til `true` for at omgå cache | -| `X-OmniRoute-Progress` | Anmodning | Indstil til `true` for fremskridtsbegivenheder | -| `Idempotency-Key` | Anmodning | Dedup nøgle (5s vindue) | -| `X-Request-Id` | Anmodning | Alternativ dedup nøgle | -| `X-OmniRoute-Cache` | Svar | `HIT` eller `MISS` (ikke-streaming) | -| `X-OmniRoute-Idempotent` | Svar | `true` hvis deduplikeret | -| `X-OmniRoute-Progress` | Svar | `enabled` hvis statussporing på | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Indlejringer +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Tilgængelige udbydere: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Billedgenerering +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Tilgængelige udbydere: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Liste over modeller +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Kompatibilitetsslutpunkter +## Compatibility Endpoints -| Metode | Sti | Format | +| Method | Path | Format | | ------ | --------------------------- | ---------------------- | | POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Antropisk | -| POST | `/v1/responses` | OpenAI-svar | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | | POST | `/v1/embeddings` | OpenAI | | POST | `/v1/images/generations` | OpenAI | -| FÅ | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Antropisk | -| FÅ | `/v1beta/models` | Tvillingerne | -| POST | `/v1beta/models/{...path}` | Gemini generer indhold | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | | POST | `/v1/api/chat` | Ollama | -### Dedikerede udbyderruter +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Udbyderpræfikset tilføjes automatisk, hvis det mangler. Umatchede modeller returnerer `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Semantisk cache +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Eksempel på svar: +Response example: ```json { @@ -164,152 +164,162 @@ Eksempel på svar: ## Dashboard & Management -### Godkendelse +### Authentication -| Slutpunkt | Metode | Beskrivelse | -| ----------------------------- | ------- | -------------------- | -| `/api/auth/login` | POST | Log ind | -| `/api/auth/logout` | POST | Log ud | -| `/api/settings/require-login` | GET/PUT | Skift login påkrævet | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Udbyderstyring +### Provider Management -| Slutpunkt | Metode | Beskrivelse | -| ---------------------------- | ------------- | ---------------------------- | -| `/api/providers` | GET/POST | Liste/opret udbydere | -| `/api/providers/[id]` | GET/SETT/SLET | Administrer en udbyder | -| `/api/providers/[id]/test` | POST | Test udbyderforbindelse | -| `/api/providers/[id]/models` | FÅ | Liste udbydermodeller | -| `/api/providers/validate` | POST | Valider udbyderkonfiguration | -| `/api/provider-nodes*` | Forskellige | Udbyder node management | -| `/api/provider-models` | GET/POST/SLET | Brugerdefinerede modeller | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth-flows +### OAuth Flows -| Slutpunkt | Metode | Beskrivelse | -| -------------------------------- | ----------- | --------------------- | -| `/api/oauth/[provider]/[action]` | Forskellige | Udbyderspecifik OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | ### Routing & Config -| Slutpunkt | Metode | Beskrivelse | -| --------------------- | ----------- | ---------------------------------- | -| `/api/models/alias` | GET/POST | Modelaliaser | -| `/api/models/catalog` | FÅ | Alle modeller efter udbyder + type | -| `/api/combos*` | Forskellige | Combo management | -| `/api/keys*` | Forskellige | API nøglestyring | -| `/api/pricing` | FÅ | Modelpriser | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Brug og analyse +### Usage & Analytics -| Slutpunkt | Metode | Beskrivelse | -| --------------------------- | ------ | ---------------------------- | -| `/api/usage/history` | FÅ | Brugshistorik | -| `/api/usage/logs` | FÅ | Brugslogs | -| `/api/usage/request-logs` | FÅ | Logfiler på anmodningsniveau | -| `/api/usage/[connectionId]` | FÅ | Brug pr. forbindelse | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Indstillinger +### Settings -| Slutpunkt | Metode | Beskrivelse | -| ------------------------------- | ------- | ----------------------------------- | -| `/api/settings` | GET/PUT | Generelle indstillinger | -| `/api/settings/proxy` | GET/PUT | Netværk proxy-konfiguration | -| `/api/settings/proxy/test` | POST | Test proxyforbindelse | -| `/api/settings/ip-filter` | GET/PUT | IP-tilladelsesliste/blokeringsliste | -| `/api/settings/thinking-budget` | GET/PUT | Begrundelse token budget | -| `/api/settings/system-prompt` | GET/PUT | Global systemprompt | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Overvågning +### Monitoring -| Slutpunkt | Metode | Beskrivelse | -| ------------------------ | ------- | --------------------- | -| `/api/sessions` | FÅ | Aktiv sessionssporing | -| `/api/rate-limits` | FÅ | Satsgrænser pr. konto | -| `/api/monitoring/health` | FÅ | Sundhedstjek | -| `/api/cache` | FÅ/SLET | Cache-statistik/ryd | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Sikkerhedskopiering og eksport/import +### Backup & Export/Import -| Slutpunkt | Metode | Beskrivelse | -| --------------------------- | ------ | -------------------------------------------- | -| `/api/db-backups` | FÅ | Liste over tilgængelige sikkerhedskopier | -| `/api/db-backups` | SÆT | Opret en manuel backup | -| `/api/db-backups` | POST | Gendan fra en specifik sikkerhedskopi | -| `/api/db-backups/export` | FÅ | Download database som .sqlite-fil | -| `/api/db-backups/import` | POST | Upload .sqlite-fil for at erstatte databasen | -| `/api/db-backups/exportAll` | FÅ | Download fuld backup som .tar.gz-arkiv | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | ### Cloud Sync -| Slutpunkt | Metode | Beskrivelse | -| ---------------------- | ----------- | -------------------------------- | -| `/api/sync/cloud` | Forskellige | Cloud-synkroniseringsoperationer | -| `/api/sync/initialize` | POST | Initialiser synkronisering | -| `/api/cloud/*` | Forskellige | Cloud management | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI-værktøjer +### CLI Tools -| Slutpunkt | Metode | Beskrivelse | -| ---------------------------------- | ------ | -------------------- | -| `/api/cli-tools/claude-settings` | FÅ | Claude CLI status | -| `/api/cli-tools/codex-settings` | FÅ | Codex CLI-status | -| `/api/cli-tools/droid-settings` | FÅ | Droid CLI status | -| `/api/cli-tools/openclaw-settings` | FÅ | OpenClaw CLI status | -| `/api/cli-tools/runtime/[toolId]` | FÅ | Generisk CLI runtime | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -CLI-svar inkluderer: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Modstandsdygtighed og satsgrænser +### ACP Agents -| Slutpunkt | Metode | Beskrivelse | -| ----------------------- | ------- | ------------------------------------ | -| `/api/resilience` | GET/PUT | Få/opdater resiliensprofiler | -| `/api/resilience/reset` | POST | Nulstil afbrydere | -| `/api/rate-limits` | FÅ | Satsgrænsestatus pr. konto | -| `/api/rate-limit` | FÅ | Global hastighedsgrænsekonfiguration | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | ### Evals -| Slutpunkt | Metode | Beskrivelse | -| ------------ | -------- | ----------------------------------- | -| `/api/evals` | GET/POST | Liste eval suiter / køre evaluering | +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -### Politikker +### Policies -| Slutpunkt | Metode | Beskrivelse | -| --------------- | ------------- | ----------------------------- | -| `/api/policies` | GET/POST/SLET | Administrer routingpolitikker | +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -### Overholdelse +### Compliance -| Slutpunkt | Metode | Beskrivelse | -| --------------------------- | ------ | ------------------------------------ | -| `/api/compliance/audit-log` | FÅ | Overholdelsesrevisionslog (sidste N) | +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### v1beta (Gemini-kompatibel) +### v1beta (Gemini-Compatible) -| Slutpunkt | Metode | Beskrivelse | -| -------------------------- | ------ | ---------------------------------- | -| `/v1beta/models` | FÅ | Vis modeller i Gemini-format | -| `/v1beta/models/{...path}` | POST | Gemini `generateContent` slutpunkt | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -Disse endepunkter afspejler Geminis API-format for klienter, der forventer indbygget Gemini SDK-kompatibilitet. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. -### Interne / System API'er +### Internal / System APIs -| Slutpunkt | Metode | Beskrivelse | -| --------------- | ------ | --------------------------------------------------------- | -| `/api/init` | FÅ | Applikationsinitieringskontrol (bruges ved første kørsel) | -| `/api/tags` | FÅ | Ollama-kompatible modelmærker (til Ollama-kunder) | -| `/api/restart` | POST | Udløs yndefuld servergenstart | -| `/api/shutdown` | POST | Udløs yndefuld serverlukning | +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | -> **Bemærk:** Disse endepunkter bruges internt af systemet eller til Ollama-klientkompatibilitet. De kaldes typisk ikke af slutbrugere. +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Lydtransskription +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transskriber lydfiler ved hjælp af Deepgram eller AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Forespørgsel:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Svar:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Understøttede udbydere:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Understøttede formater:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Ollama-kompatibilitet +## Ollama Compatibility -For klienter, der bruger Ollamas API-format: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Forespørgsler oversættes automatisk mellem Ollama og interne formater. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetri +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Svar:** +**Response:** ```json { @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Modeltilgængelighed +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Anmodningsbehandling +## Request Processing -1. Klient sender anmodning til `/v1/*` -2. Rutehandler kalder `handleChat`, `handleEmbedding`, `handleAudioTranscription` eller `handleImageGeneration` -3. Modellen er løst (direkte udbyder/model eller alias/kombination) -4. Oplysninger valgt fra lokal DB med filtrering af kontotilgængelighed -5. Til chat: `handleChatCore` — formatdetektion, oversættelse, cachecheck, idempotenstjek -6. Udbyder eksekutør sender upstream anmodning -7. Svar oversat tilbage til klientformat (chat) eller returneret som det er (indlejringer/billeder/lyd) -8. Brug/logning registreret -9. Fallback gælder for fejl i henhold til combo regler +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Fuld arkitekturreference: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Godkendelse +## Authentication -- Dashboard-ruter (`/dashboard/*`) bruger `auth_token`-cookie -- Login bruger gemt adgangskode-hash; tilbagefald til `INITIAL_PASSWORD` -- `requireLogin` kan skiftes via `/api/settings/require-login` -- `/v1/*`-ruter kræver valgfrit Bearer API-nøgle, når `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/da/ARCHITECTURE.md b/docs/i18n/da/ARCHITECTURE.md index d06dea0141..258d62df53 100644 --- a/docs/i18n/da/ARCHITECTURE.md +++ b/docs/i18n/da/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# OmniRoute-arkitektur +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Sidst opdateret: 2026-02-18_ +_Last updated: 2026-03-04_ -## Resumé +## Executive Summary -OmniRoute er en lokal AI-routinggateway og dashboard bygget på Next.js. -Det giver et enkelt OpenAI-kompatibelt slutpunkt (`/v1/*`) og dirigerer trafik på tværs af flere upstream-udbydere med oversættelse, fallback, token-opdatering og brugssporing. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Kerneegenskaber: +Core capabilities: -- OpenAI-kompatibel API-overflade til CLI/værktøjer (28 udbydere) -- Anmodning/svar oversættelse på tværs af udbyderformater -- Model combo fallback (multi-model sekvens) -- Fallback på kontoniveau (multi-konto pr. udbyder) -- Administration af forbindelse til OAuth + API-nøgleudbyder -- Indlejringsgenerering via `/v1/embeddings` (6 udbydere, 9 modeller) -- Billedgenerering via `/v1/images/generations` (4 udbydere, 9 modeller) -- Tænk tag-parsing (`...`) for ræsonneringsmodeller -- Response sanitization for streng OpenAI SDK-kompatibilitet -- Rollenormalisering (udvikler→system, system→bruger) for kompatibilitet på tværs af udbydere -- Struktureret outputkonvertering (json_schema → Gemini responseSchema) -- Lokal persistens for udbydere, nøgler, aliaser, kombinationer, indstillinger, priser -- Brug/omkostningssporing og anmodningslogning -- Valgfri skysynkronisering til synkronisering af flere enheder/tilstande -- IP-tilladelsesliste/blokeringsliste til API-adgangskontrol -- Tænkende budgetstyring (passthrough/auto/custom/adaptive) -- Global system prompt injektion -- Sessionssporing og fingeraftryk -- Forbedret prisbegrænsning pr. konto med udbyderspecifikke profiler -- Circuit breaker mønster for udbyderens modstandsdygtighed -- Anti-tordenbeskyttelse med mutex-låsning -- Signaturbaseret anmodnings deduplikeringscache -- Domænelag: modeltilgængelighed, omkostningsregler, fallback-politik, lockout-politik -- Vedvarende domænetilstand (SQLite-gennemskrivningscache til fallbacks, budgetter, lockouts, strømafbrydere) -- Politikmotor til centraliseret anmodningsevaluering (lockout → budget → fallback) -- Anmod om telemetri med p50/p95/p99 latency aggregering -- Korrelations-ID (X-Request-Id) til ende-til-ende-sporing -- Overholdelsesrevisionslogning med opt-out pr. API-nøgle -- Evalueringsramme for LLM kvalitetssikring -- Resilience UI-dashboard med strømafbryderstatus i realtid -- Modulære OAuth-udbydere (12 individuelle moduler under `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Primær runtime model: +Primary runtime model: -- Next.js app-ruter under `src/app/api/*` implementerer både dashboard-API'er og kompatibilitets-API'er -- En delt SSE/routingkerne i `src/sse/*` + `open-sse/*` håndterer udbyderens udførelse, oversættelse, streaming, fallback og brug +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Omfang og grænser +## Scope and Boundaries -### I omfang +### In Scope -- Lokal gateway køretid -- Dashboard management API'er -- Udbydergodkendelse og tokenopdatering -- Anmod om oversættelse og SSE-streaming -- Lokal stat + vedvarende brug -- Valgfri skysynkroniseringsorkestrering +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Uden for anvendelsesområde +### Out of Scope -- Cloud-tjenesteimplementering bag `NEXT_PUBLIC_CLOUD_URL` -- Udbyder SLA/kontrolplan uden for lokal proces -- Eksterne CLI-binære filer selv (Claude CLI, Codex CLI osv.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Systemkontekst på højt niveau +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -115,149 +115,150 @@ flowchart LR ## Core Runtime Components -## 1) API og Routing Layer (Next.js App Routes) +## 1) API and Routing Layer (Next.js App Routes) -Hovedmapper: +Main directories: -- `src/app/api/v1/*` og `src/app/api/v1beta/*` for kompatibilitets-API'er -- `src/app/api/*` til administrations-/konfigurations-API'er -- Næste omskrivninger i `next.config.mjs` kort `/v1/*` til `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Vigtige kompatibilitetsruter: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — inkluderer brugerdefinerede modeller med `custom: true` -- `src/app/api/v1/embeddings/route.ts` — indlejringsgenerering (6 udbydere) -- `src/app/api/v1/images/generations/route.ts` — billedgenerering (4+ udbydere inkl. Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedikeret chat pr. udbyder -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedikerede indlejringer pr. udbyder -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedikerede billeder pr. udbyder +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Ledelsesdomæner: +Management domains: -- Godkendelse/indstillinger: `src/app/api/auth/*`, `src/app/api/settings/*` -- Udbydere/forbindelser: `src/app/api/providers*` -- Udbyder noder: `src/app/api/provider-nodes*` -- Brugerdefinerede modeller: `src/app/api/provider-models` (GET/POST/DELETE) -- Modelkatalog: `src/app/api/models/catalog` (GET) -- Proxy-konfiguration: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Nøgler/aliaser/kombinationer/priser: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Anvendelse: `src/app/api/usage/*` -- Synkroniser/sky: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI-værktøjshjælpere: `src/app/api/cli-tools/*` -- IP-filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Tænkende budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- Systemprompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessioner: `src/app/api/sessions` (GET) -- Satsgrænser: `src/app/api/rate-limits` (GET) -- Modstandsdygtighed: `src/app/api/resilience` (GET/PATCH) — udbyderprofiler, strømafbryder, hastighedsgrænsetilstand -- Resilience reset: `src/app/api/resilience/reset` (POST) — nulstil breakers + cooldowns -- Cachestatistik: `src/app/api/cache/stats` (GET/DELETE) -- Modeltilgængelighed: `src/app/api/models/availability` (GET/POST) -- Telemetri: `src/app/api/telemetry/summary` (GET) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) - Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback-kæder: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Overholdelsesrevision: `src/app/api/compliance/audit-log` (GET) -- Evaler: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Politikker: `src/app/api/policies` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Oversættelseskerne +## 2) SSE + Translation Core -Hovedflowmoduler: +Main flow modules: -- Indgang: `src/sse/handlers/chat.ts` -- Kerneorkestrering: `open-sse/handlers/chatCore.ts` -- Leverandørudførelsesadaptere: `open-sse/executors/*` -- Formatdetektion/udbyderkonfiguration: `open-sse/services/provider.ts` -- Modelparse/opløsning: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Konto fallback logik: `open-sse/services/accountFallback.ts` -- Oversættelsesregister: `open-sse/translator/index.ts` -- Strømtransformationer: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Brugsekstraktion/normalisering: `open-sse/utils/usageTracking.ts` -- Tænk tag-parser: `open-sse/utils/thinkTagParser.ts` -- Indlejringshåndtering: `open-sse/handlers/embeddings.ts` -- Indlejring af udbyderregistrering: `open-sse/config/embeddingRegistry.ts` -- Billedgenereringsbehandler: `open-sse/handlers/imageGeneration.ts` -- Billedudbyderregistrering: `open-sse/config/imageRegistry.ts` -- Reaktionssanering: `open-sse/handlers/responseSanitizer.ts` -- Rollenormalisering: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Tjenester (forretningslogik): +Services (business logic): -- Kontovalg/score: `open-sse/services/accountSelector.ts` -- Kontekstlivscyklusstyring: `open-sse/services/contextManager.ts` -- Håndhævelse af IP-filter: `open-sse/services/ipFilter.ts` -- Sessionssporing: `open-sse/services/sessionManager.ts` -- Anmod om deduplikering: `open-sse/services/signatureCache.ts` -- Systemprompt indsprøjtning: `open-sse/services/systemPrompt.ts` -- Tænkende budgetstyring: `open-sse/services/thinkingBudget.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` - Wildcard model routing: `open-sse/services/wildcardRouter.ts` -- Satsgrænsestyring: `open-sse/services/rateLimitManager.ts` -- Afbryder: `open-sse/services/circuitBreaker.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Domænelagsmoduler: +Domain layer modules: -- Modeltilgængelighed: `src/lib/domain/modelAvailability.ts` -- Omkostningsregler/budgetter: `src/lib/domain/costRules.ts` -- Fallback-politik: `src/lib/domain/fallbackPolicy.ts` +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` - Combo resolver: `src/lib/domain/comboResolver.ts` -- Lockout-politik: `src/lib/domain/lockoutPolicy.ts` -- Politikmotor: `src/domain/policyEngine.ts` — centraliseret lockout → budget → fallback-evaluering -- Fejlkodekatalog: `src/lib/domain/errorCodes.ts` -- Anmodnings-id: `src/lib/domain/requestId.ts` -- Hente timeout: `src/lib/domain/fetchTimeout.ts` -- Anmod om telemetri: `src/lib/domain/requestTelemetry.ts` -- Overholdelse/revision: `src/lib/domain/compliance/index.ts` -- Evalløber: `src/lib/domain/evalRunner.ts` -- Vedvarende domænetilstand: `src/lib/db/domainState.ts` — SQLite CRUD til reservekæder, budgetter, omkostningshistorik, lockouttilstand, afbrydere +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth-udbydermoduler (12 individuelle filer under `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Registerindeks: `src/lib/oauth/providers/index.ts` -- Individuelle udbydere: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, , , `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Tyndt omslag: `src/lib/oauth/providers.ts` — reeksport fra individuelle moduler +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Persistens-lag +## 3) Persistence Layer -Primær tilstand DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- fil: `${DATA_DIR}/db.json` (eller `$XDG_CONFIG_HOME/omniroute/db.json` når indstillet, ellers `~/.omniroute/db.json`) -- enheder: providerConnections, providerNodes, modelAliaser, combos, apiKeys, indstillinger, prissætning, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Brug DB: +Usage persistence: -- `src/lib/usageDb.ts` -- filer: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- følger den samme grundlæggende bibliotekspolitik som `localDb` (`DATA_DIR`, derefter `XDG_CONFIG_HOME/omniroute`, når den er indstillet) -- opdelt i fokuserede undermoduler: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — CRUD-operationer for domænetilstand -- Tabeller (oprettet i `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Gennemskrivningscachemønster: Kort i hukommelsen er autoritative under kørsel; mutationer skrives synkront til SQLite; tilstand gendannes fra DB ved koldstart +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Auth + Sikkerhedsoverflader +## 4) Auth + Security Surfaces -- Dashboard-cookiegodkendelse: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Generering/bekræftelse af API-nøgler: `src/shared/utils/apiKey.ts` -- Udbyderhemmeligheder bestod i `providerConnections` poster -- Udgående proxy-understøttelse via `open-sse/utils/proxyFetch.ts` (env vars) og `open-sse/utils/networkProxy.ts` (konfigurerbar pr. udbyder eller global) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) ## 5) Cloud Sync -- Planlægger init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Periodisk opgave: `src/shared/services/cloudSyncScheduler.ts` -- Kontrolrute: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Anmod om livscyklus (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Fallback-beslutninger er drevet af `open-sse/services/accountFallback.ts` ved hjælp af statuskoder og fejlmeddelelsesheuristik. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth Onboarding og Token Refresh Lifecycle +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Opdatering under live-trafik udføres inde i `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Cloud Sync Lifecycle (Aktiver / Synkroniser / Deaktiver) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Periodisk synkronisering udløses af `CloudSyncScheduler`, når skyen er aktiveret. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Datamodel og lagerkort +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Fysiske lagerfiler: +Physical storage files: -- hovedtilstand: `${DATA_DIR}/db.json` (eller `$XDG_CONFIG_HOME/omniroute/db.json` når indstillet, ellers `~/.omniroute/db.json`) -- brugsstatistik: `${DATA_DIR}/usage.json` -- anmod om log linjer: `${DATA_DIR}/log.txt` -- valgfri oversætter/anmodningsfejlfindingssessioner: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Implementeringstopologi +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Modulkortlægning (beslutningskritisk) +## Module Mapping (Decision-Critical) -### Rute- og API-moduler +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: kompatibilitets-API'er -- `src/app/api/v1/providers/[provider]/*`: dedikerede ruter pr. udbyder (chat, indlejringer, billeder) -- `src/app/api/providers*`: udbyder CRUD, validering, test -- `src/app/api/provider-nodes*`: brugerdefineret kompatibel nodestyring -- `src/app/api/provider-models`: brugerdefineret modelstyring (CRUD) -- `src/app/api/models/catalog`: komplet modelkatalog API (alle typer grupperet efter udbyder) -- `src/app/api/oauth/*`: OAuth/enhedskode-flows -- `src/app/api/keys*`: lokal API nøgle livscyklus +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle - `src/app/api/models/alias`: alias management - `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pristilsidesættelser til omkostningsberegning -- `src/app/api/settings/proxy`: proxy-konfiguration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: test af udgående proxyforbindelse (POST) -- `src/app/api/usage/*`: brugs- og log-API'er -- `src/app/api/sync/*` + `src/app/api/cloud/*`: skysynkronisering og skyvendte hjælpere -- `src/app/api/cli-tools/*`: lokale CLI-konfigurationsskrivere/-brikker -- `src/app/api/settings/ip-filter`: IP-tilladelsesliste/blokeringsliste (GET/PUT) -- `src/app/api/settings/thinking-budget`: Tænkende token-budgetkonfiguration (GET/PUT) -- `src/app/api/settings/system-prompt`: global systemprompt (GET/PUT) -- `src/app/api/sessions`: aktiv sessionsfortegnelse (GET) -- `src/app/api/rate-limits`: satsgrænsestatus pr. konto (GET) +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Routing og udførelseskerne +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: anmodning om parse, kombinationshåndtering, kontovalgsløkke -- `open-sse/handlers/chatCore.ts`: oversættelse, eksekutorafsendelse, genforsøg/opdateringshåndtering, stream-opsætning -- `open-sse/executors/*`: udbyderspecifik netværks- og formatadfærd +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Oversættelsesregister og formatkonvertere +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: oversætterregister og orkestrering -- Anmod om oversættere: `open-sse/translator/request/*` -- Svaroversættere: `open-sse/translator/response/*` -- Formatkonstanter: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Vedholdenhed +### Persistence -- `src/lib/localDb.ts`: vedvarende konfiguration/tilstand -- `src/lib/usageDb.ts`: brugshistorik og rullende anmodningslogfiler +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Udbyder Eksekutør Dækning (Strategimønster) +## Provider Executor Coverage (Strategy Pattern) -Hver udbyder har en specialiseret udfører, der udvider `BaseExecutor` (i `open-sse/executors/base.ts`), som giver URL-opbygning, header-konstruktion, genforsøg med eksponentiel backoff, legitimationsopdateringshook og `execute()` orkestreringsmetoden. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Eksekutør | Udbyder(e) | Særlig håndtering | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fyrværkeri, Cerebras, Cohere, NVIDIA | Dynamisk URL/header-konfiguration pr. udbyder | -| `AntigravityExecutor` | Google Antigravity | Brugerdefinerede projekt-/sessions-id'er, forsøg igen - efter parsing | -| `CodexExecutor` | OpenAI Codex | Injicerer systeminstruktioner, fremtvinger ræsonnement indsats | -| `CursorExecutor` | Markør IDE | ConnectRPC-protokol, Protobuf-kodning, anmodningssignering via checksum | -| `GithubExecutor` | GitHub Copilot | Copilot token opdatering, VSCode-mimicing headers | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binært format → SSE-konvertering | -| `GeminiCLIExecutor` | Gemini CLI | Opdateringscyklus for Google OAuth-token | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Alle andre udbydere (inklusive brugerdefinerede kompatible noder) bruger `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Udbyderkompatibilitetsmatrix +## Provider Compatibility Matrix -| Udbyder | Format | Auth | Stream | Ikke-stream | Token Opdater | Brug API | -| ---------------- | --------------- | --------------------- | ---------------- | ----------- | ------------- | -------------------- | -| Claude | claude | API-nøgle / OAuth | ✅ | ✅ | ✅ | ⚠️ Kun administrator | -| Tvillingerne | gemini | API-nøgle / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Antigravitation | antityngdekraft | OAuth | ✅ | ✅ | ✅ | ✅ Fuld kvote API | -| OpenAI | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-svar | OAuth | ✅ tvunget | ❌ | ✅ | ✅ Satsgrænser | -| GitHub Copilot | åbne | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Kvote snapshots | -| Markør | markør | Tilpasset kontrolsum | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Brugsgrænser | -| Qwen | åbne | OAuth | ✅ | ✅ | ✅ | ⚠️ Efter anmodning | -| iFlow | åbne | OAuth (Grundlæggende) | ✅ | ✅ | ✅ | ⚠️ Efter anmodning | -| OpenRouter | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| Groq | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| Mistral | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| Forvirring | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| Sammen AI | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| Fyrværkeri AI | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| Cerebras | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| Sammenhæng | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | åbne | API-nøgle | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Format oversættelsesdækning +## Format Translation Coverage -Detekterede kildeformater omfatter: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Målformater omfatter: +Target formats include: -- OpenAI chat/svar +- OpenAI chat/Responses - Claude -- Gemini/Gemini-CLI/Antigravity kuvert +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Markør +- Cursor -Oversættelser bruger **OpenAI som hub-format** - alle konverteringer går gennem OpenAI som mellemliggende: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Oversættelser vælges dynamisk baseret på kildens nyttelastform og udbyderens målformat. +Translations are selected dynamically based on source payload shape and provider target format. -Yderligere behandlingslag i oversættelsespipelinen: +Additional processing layers in the translation pipeline: -- **Responssanering** — Fjerner ikke-standardfelter fra OpenAI-formatsvar (både streaming og ikke-streaming) for at sikre streng SDK-overholdelse -- **Rollenormalisering** — Konverterer `developer` → `system` til ikke-OpenAI-mål; fusionerer `system` → `user` for modeller, der afviser systemrollen (GLM, ERNIE) -- **Tænk tag-udtrækning** — Parser `...` blokke fra indhold til feltet `reasoning_content` -- **Struktureret output** — Konverterer OpenAI `response_format.json_schema` til Gemini's `responseMimeType` + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Understøttede API-endepunkter +## Supported API Endpoints -| Slutpunkt | Format | Behandler | -| -------------------------------------------------- | ------------------------- | ------------------------------------------------------------------ | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Beskeder | Samme handler (auto-detekteret) | -| `POST /v1/responses` | OpenAI-svar | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI-indlejringer | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Modelliste | API-rute | -| `POST /v1/images/generations` | OpenAI Billeder | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Modelliste | API-rute | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedikeret per udbyder med modelvalidering | -| `POST /v1/providers/{provider}/embeddings` | OpenAI-indlejringer | Dedikeret per udbyder med modelvalidering | -| `POST /v1/providers/{provider}/images/generations` | OpenAI Billeder | Dedikeret per udbyder med modelvalidering | -| `POST /v1/messages/count_tokens` | Claude Token Count | API-rute | -| `GET /v1/models` | OpenAI Models liste | API-rute (chat + indlejring + billede + brugerdefinerede modeller) | -| `GET /api/models/catalog` | Katalog | Alle modeller grupperet efter udbyder + type | -| `POST /v1beta/models/*:streamGenerateContent` | Tvilling hjemmehørende | API-rute | -| `GET/PUT/DELETE /api/settings/proxy` | Proxy-konfiguration | Netværk proxy-konfiguration | -| `POST /api/settings/proxy/test` | Proxy-forbindelse | Proxy-sundheds-/forbindelsestestslutpunkt | -| `GET/POST/DELETE /api/provider-models` | Brugerdefinerede modeller | Brugerdefineret modelstyring pr. udbyder | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | ## Bypass Handler -Bypass-handleren (`open-sse/utils/bypassHandler.ts`) opsnapper kendte "smid-anmodninger" fra Claude CLI - opvarmningsping, titeludtræk og tokentællinger - og returnerer et **falsk svar** uden at forbruge upstream-udbydertokens. Dette udløses kun, når `User-Agent` indeholder `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Anmod om Logger Pipeline +## Request Logger Pipeline -Anmodningsloggeren (`open-sse/utils/requestLogger.ts`) giver en 7-trins debug-logningspipeline, deaktiveret som standard, aktiveret via `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Filer skrives til `/logs//` for hver anmodningssession. +Files are written to `/logs//` for each request session. -## Fejltilstande og modstandsdygtighed +## Failure Modes and Resilience -## 1) Konto/udbyder tilgængelighed +## 1) Account/Provider Availability -- Nedkøling af udbyderkonto på forbigående/rate/godkendelsesfejl -- konto fallback før mislykket anmodning -- combo model fallback, når den nuværende model/udbydersti er udtømt +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Tokens udløb +## 2) Token Expiry -- Forhåndstjek og opdater med genforsøg for udbydere, der kan opdateres -- 401/403 forsøg igen efter opdateringsforsøg i kernestien +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Strømsikkerhed +## 3) Stream Safety -- afbrydelsesbevidst streamcontroller -- translationsstream med end-of-stream flush og `[DONE]` håndtering -- forbrugsestimeret fallback, når udbyderens brugsmetadata mangler +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Cloud Sync-forringelse +## 4) Cloud Sync Degradation -- Synkroniseringsfejl dukker op, men lokal kørsel fortsætter -- Scheduler har logik, der kan genforsøge, men periodisk udførelse kalder i øjeblikket enkelt-forsøgssynkronisering som standard +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Dataintegritet +## 5) Data Integrity -- DB shape migration/reparation for manglende nøgler -- korrupte JSON-nulstillingsbeskyttelsesforanstaltninger for localDb og usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Observerbarhed og operationelle signaler +## Observability and Operational Signals -Kilder til synlighed ved kørsel: +Runtime visibility sources: -- konsollogfiler fra `src/sse/utils/logger.ts` -- brugsaggregater pr. anmodning i `usage.json` -- log på status for tekstanmodning `log.txt` -- valgfri dybe anmodnings-/oversættelseslogfiler under `logs/` når `ENABLE_REQUEST_LOGS=true` -- dashboardbrugsendepunkter (`/api/usage/*`) for brugergrænsefladeforbrug +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Sikkerhedsfølsomme grænser +## Security-Sensitive Boundaries -- JWT-hemmelighed (`JWT_SECRET`) sikrer bekræftelse/signering af dashboard-sessionscookie -- Indledende adgangskode fallback (`INITIAL_PASSWORD`, standard `123456`) skal tilsidesættes i rigtige implementeringer -- API-nøgle HMAC-hemmelighed (`API_KEY_SECRET`) sikrer genereret lokalt API-nøgleformat -- Udbyderhemmeligheder (API-nøgler/tokens) bevares i lokal DB og bør beskyttes på filsystemniveau -- Slutpunkter for skysynkronisering er afhængige af API-nøglegodkendelse + maskin-id-semantik +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Miljø og Runtime Matrix +## Environment and Runtime Matrix -Miljøvariabler aktivt brugt af kode: +Environment variables actively used by code: -- App/godkendelse: `JWT_SECRET`, `INITIAL_PASSWORD` -- Opbevaring: `DATA_DIR` -- Kompatibel nodeadfærd: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Valgfri lagerbasetilsidesættelse (Linux/macOS, når `DATA_DIR` ikke er indstillet): `XDG_CONFIG_HOME` -- Sikkerhedshashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Logning: `ENABLE_REQUEST_LOGS` -- Synkronisering/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Udgående proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` og varianter med små bogstaver -- SOCKS5-funktionsflag: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Platform-/runtime-hjælpere (ikke app-specifik konfiguration): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Kendte arkitektoniske noter +## Known Architectural Notes -1. `usageDb` og `localDb` deler nu den samme grundlæggende bibliotekspolitik (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) med ældre filmigrering. -2. `/api/v1/route.ts` returnerer en statisk modelliste og er ikke den primære modelkilde, der bruges af `/v1/models`. -3. Anmodningslogger skriver hele headers/body, når den er aktiveret; behandle logbiblioteket som følsomt. -4. Cloudadfærd afhænger af korrekt `NEXT_PUBLIC_BASE_URL` og cloud-endepunkters tilgængelighed. -5. `open-sse/` biblioteket udgives som `@omniroute/open-sse` **npm workspace-pakken**. Kildekoden importerer det via `@omniroute/open-sse/...` (løst af Next.js `transpilePackages`). Filstier i dette dokument bruger stadig mappenavnet `open-sse/` for at opnå konsistens. -6. Diagrammer i dashboardet bruger **Recharts** (SVG-baseret) til tilgængelige, interaktive analysevisualiseringer (søjlediagrammer for modelbrug, udbyderopdelingstabeller med succesrater). -7. E2E-tests bruger **Playwright** (`tests/e2e/`), køres via `npm run test:e2e`. Enhedstests bruger **Node.js testløber** (`tests/unit/`), køres via `npm run test:plan3`. Kildekoden under `src/` er **TypeScript** (`.ts`/`.tsx`); `open-sse/`-arbejdsområdet forbliver JavaScript (`.js`). -8. Siden Indstillinger er organiseret i 5 faner: Sikkerhed, Routing (6 globale strategier: fill-first, round-robin, p2c, random, mindst brugt, omkostningsoptimeret), Resiliens (redigerbare hastighedsgrænser, strømafbryder, politikker), AI (tænkebudget, systemprompt, promptcache), Avanceret (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Tjekliste for operationel verifikation +## Operational Verification Checklist -- Byg fra kilde: `npm run build` -- Byg Docker-billede: `docker build -t omniroute .` -- Start service og bekræft: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- CLI-målbasis-URL skal være `http://:20128/v1`, når `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/da/CODEBASE_DOCUMENTATION.md b/docs/i18n/da/CODEBASE_DOCUMENTATION.md index d255187977..303880c198 100644 --- a/docs/i18n/da/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/da/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Kodebasedokumentation +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> En omfattende, begyndervenlig guide til **omniroute** multi-udbyder AI proxy-routeren. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Hvad er omniroute? +## 1. What Is omniroute? -omniroute er en **proxy-router**, der sidder mellem AI-klienter (Claude CLI, Codex, Cursor IDE osv.) og AI-udbydere (Anthropic, Google, OpenAI, AWS, GitHub osv.). Det løser et stort problem: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Forskellige AI-klienter taler forskellige "sprog" (API-formater), og forskellige AI-udbydere forventer også forskellige "sprog".** omniroute oversætter mellem dem automatisk. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Tænk på det som en universel oversætter i FN - enhver delegeret kan tale et hvilket som helst sprog, og oversætteren konverterer det til enhver anden delegeret. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Arkitekturoversigt +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Kerneprincip: Hub-and-Speake-oversættelse +### Core Principle: Hub-and-Spoke Translation -Al formatoversættelse passerer gennem **OpenAI-formatet som hub**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Det betyder, at du kun behøver **N oversættere** (én pr. format) i stedet for **N²** (hvert par). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Projektstruktur +## 3. Project Structure ``` omniroute/ @@ -104,20 +104,20 @@ omniroute/ --- -## 4. Modul-for-modul-opdeling +## 4. Module-by-Module Breakdown ### 4.1 Config (`open-sse/config/`) -Den **enkelte kilde til sandhed** for alle udbyderkonfigurationer. +The **single source of truth** for all provider configuration. -| Fil | Formål | -| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` objekt med basis-URL'er, OAuth-legitimationsoplysninger (standarder), headere og standardsystemprompter for hver udbyder. Definerer også `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` og `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Indlæser eksterne legitimationsoplysninger fra `data/provider-credentials.json` og fletter dem over de hårdkodede standardindstillinger i `PROVIDERS`. Holder hemmeligheder uden for kildekontrol og bevarer bagudkompatibilitet. | -| `providerModels.ts` | Central modelregistrering: kortudbyderaliasser → model-id'er. Funktioner som `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Systeminstruktioner indsat i Codex-anmodninger (redigeringsbegrænsninger, sandkasseregler, godkendelsespolitikker). | -| `defaultThinkingSignature.ts` | Standard "tænkende" signaturer for Claude og Gemini modeller. | -| `ollamaModels.ts` | Skemadefinition for lokale Ollama-modeller (navn, størrelse, familie, kvantisering). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | #### Credential Loading Flow @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Eksekutører (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Eksekutører indkapsler **udbyderspecifik logik** ved hjælp af **Strategy Pattern**. Hver executor tilsidesætter basismetoder efter behov. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Eksekutør | Udbyder | Nøglespecialiseringer | -| ---------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Abstrakt base: URL-opbygning, overskrifter, genforsøgslogik, opdatering af legitimationsoplysninger | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generisk OAuth-tokenopdatering til standardudbydere | -| `antigravity.ts` | Google Cloud-kode | Generering af projekt-/sessions-id, multi-URL fallback, brugerdefineret genforsøg at parse fra fejlmeddelelser ("nulstil efter 2t7m23s") | -| `cursor.ts` | Markør IDE | **Mest kompleks**: SHA-256 checksum auth, Protobuf request encoding, binær EventStream → SSE respons parsing | -| `codex.ts` | OpenAI Codex | Injicerer systeminstruktioner, styrer tankeniveauer, fjerner ikke-understøttede parametre | -| `gemini-cli.ts` | Google Gemini CLI | Opbygning af tilpasset URL (`streamGenerateContent`), opdatering af Google OAuth-token | -| `github.ts` | GitHub Copilot | Dobbelt token-system (GitHub OAuth + Copilot-token), VSCode-header-efterligning | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binær parsing, AMZN hændelsesrammer, token estimering | -| `index.ts` | — | Fabrik: navn på kortudbyder → eksekveringsklasse, med standard fallback | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Håndtere (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**Orkestreringslaget** — koordinerer oversættelse, udførelse, streaming og fejlhåndtering. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Fil | Formål | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `chatCore.ts` | **Central orkestrator** (~600 linjer). Håndterer hele forespørgselslivscyklussen: formatdetektion → oversættelse → eksekutørafsendelse → streaming/ikke-streamingsvar → token-opdatering → fejlhåndtering → logføring af brug. | -| `responsesHandler.ts` | Adapter til OpenAI's Responses API: konverterer svarformat → Chatfuldførelser → sender til `chatCore` → konverterer SSE tilbage til svarformat. | -| `embeddings.ts` | Indlejringsgenereringshåndtering: løser indlejringsmodel → udbyder, sender til udbyder API, returnerer OpenAI-kompatibelt indlejringssvar. Understøtter 6+ udbydere. | -| `imageGeneration.ts` | Billedgenereringshåndtering: løser billedmodel → udbyder, understøtter OpenAI-kompatibel, Gemini-image (Antigravity) og fallback (Nebius) tilstande. Returnerer base64- eller URL-billeder. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Anmod om livscyklus (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,26 +258,26 @@ sequenceDiagram --- -### 4.4 Tjenester (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Forretningslogik, der understøtter behandlerne og udførerne. +Business logic that supports the handlers and executors. -| Fil | Formål | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Formatregistrering** (`detectFormat`): analyser anmoder om kropsstruktur for at identificere Claude/OpenAI/Gemini/Antigravity/Responses-formater (inkluderer `max_tokens` heuristik for Claude). Også: URL-opbygning, header-opbygning, normalisering af tænkekonfig. Understøtter `openai-compatible-*` og `anthropic-compatible-*` dynamiske udbydere. | -| `model.ts` | Modelstrengparsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias-opløsning med kollisionsdetektion, input-sanering (afviser stigennemgang/kontroltegn) og modelinformationsopløsning med understøttelse af async alias getter. | -| `accountFallback.ts` | Håndtering af hastighedsgrænser: eksponentiel backoff (1s → 2s → 4s → max 2min), kontoafkølingsstyring, fejlklassificering (hvilke fejl udløser fallback vs. ikke). | -| `tokenRefresh.ts` | Opdatering af OAuth-token for **alle udbydere**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Inkluderer under flyvning lover deduplikation cache og forsøg igen med eksponentiel backoff. | -| `combo.ts` | **Combo-modeller**: kæder af reservemodeller. Hvis model A fejler med en fallback-kvalificeret fejl, prøv model B, derefter C osv. Returnerer faktiske upstream-statuskoder. | -| `usage.ts` | Henter kvote-/brugsdata fra udbyder-API'er (GitHub Copilot-kvoter, Antigravity-modelkvoter, Codex-hastighedsgrænser, Kiro-brugsopdelinger, Claude-indstillinger). | -| `accountSelector.ts` | Smart kontovalg med scoringsalgoritme: overvejer prioritet, sundhedsstatus, round-robin-position og nedkølingstilstand for at vælge den optimale konto for hver anmodning. | -| `contextManager.ts` | Anmodningskontekstlivscyklusstyring: opretter og sporer kontekstobjekter pr. anmodning med metadata (anmodnings-id, tidsstempler, udbyderoplysninger) til fejlretning og logning. | -| `ipFilter.ts` | IP-baseret adgangskontrol: understøtter tilladelsesliste og bloklistetilstande. Validerer klient-IP mod konfigurerede regler, før API-anmodninger behandles. | -| `sessionManager.ts` | Sessionssporing med klientfingeraftryk: sporer aktive sessioner ved hjælp af hashed klient-id'er, overvåger antallet af anmodninger og leverer sessionsmetrics. | -| `signatureCache.ts` | Anmod om signaturbaseret deduplikeringscache: forhindrer duplikerede anmodninger ved at cache de seneste anmodningssignaturer og returnere cachelagrede svar for identiske anmodninger inden for et tidsvindue. | -| `systemPrompt.ts` | Global systemprompt-injektion: forudsætter eller tilføjer en konfigurerbar systemprompt til alle anmodninger med kompatibilitetshåndtering pr. udbyder. | -| `thinkingBudget.ts` | Reasoning token budget management: understøtter passthrough, auto (strip thinking config), brugerdefineret (fast budget) og adaptive (kompleksitetsskaleret) tilstande til at kontrollere tanke/ræsonnement tokens. | -| `wildcardRouter.ts` | Routing af jokertegnmodelmønster: løser jokertegnmønstre (f.eks. `*/claude-*`) til konkrete udbyder/modelpar baseret på tilgængelighed og prioritet. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | #### Token Refresh Deduplication @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Kombi-modelkæde +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Oversætter (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**formatoversættelsesmotoren** ved hjælp af et selvregistrerende plugin-system. +The **format translation engine** using a self-registering plugin system. -#### Arkitektur +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Katalog | Filer | Beskrivelse | -| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 oversættere | Konverter anmodningstekster mellem formater. Hver fil selvregistreres via `register(from, to, fn)` ved import. | -| `response/` | 7 oversættere | Konverter streamingsvarstykker mellem formater. Håndterer SSE-hændelsestyper, tænkeblokke, værktøjskald. | -| `helpers/` | 6 hjælpere | Delte hjælpeprogrammer: `claudeHelper` (udtræk af systemprompt, tænkekonfiguration), `geminiHelper` (kortlægning af dele/indhold), `openaiHelper` (formatfiltrering), `toolCallHelper` (ID-generering, manglende svarindsprøjtning), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Oversættelsesmaskine: `translateRequest()`, `translateResponse()`, statsledelse, register. | -| `formats.ts` | — | Formatkonstanter: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Nøgledesign: Selvregistrerende plugins +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -397,15 +397,15 @@ import "./request/claude-to-openai.js"; // ← self-registers ### 4.6 Utils (`open-sse/utils/`) -| Fil | Formål | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Opbygning af fejlsvar (OpenAI-kompatibelt format), upstream fejlparsing, Antigravity genforsøgstidsudtrækning fra fejlmeddelelser, SSE fejlstreaming. | -| `stream.ts` | **SSE Transform Stream** — den centrale streamingpipeline. To tilstande: `TRANSLATE` (fuldformatoversættelse) og `PASSTHROUGH` (normalisering + ekstraktionsbrug). Håndterer chunk-buffring, brugsestimering, indholdslængdesporing. Per-stream encoder/decoder-instanser undgår delt tilstand. | -| `streamHelpers.ts` | SSE-værktøjer på lavt niveau: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filtrerer tomme bidder til OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-bevidst SSETOKEN_101\*\* oprydning med oprydning med ). | -| `usageTracking.ts` | Udtræk af tokenbrug fra ethvert format (Claude/OpenAI/Gemini/Responses), estimering med separate værktøj/meddelelse-char-per-token-forhold, buffertilsætning (2000 tokens sikkerhedsmargen), formatspecifik feltfiltrering, konsollogning med ANSI-farver. | -| `requestLogger.ts` | Filbaseret anmodningslogning (tilmelding via `ENABLE_REQUEST_LOGS=true`). Opretter sessionsmapper med nummererede filer: `1_req_client.json` → `7_res_client.txt`. Alle I/O er asynkrone (fire-and-forget). Masker følsomme overskrifter. | -| `bypassHandler.ts` | Opsnapper specifikke mønstre fra Claude CLI (titeludtræk, opvarmning, optælling) og returnerer falske svar uden at ringe til nogen udbyder. Understøtter både streaming og ikke-streaming. Med vilje begrænset til Claude CLI-omfang. | -| `networkProxy.ts` | Løser udgående proxy-URL for en given udbyder med forrang: udbyderspecifik konfiguration → global konfiguration → miljøvariabler (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Understøtter `NO_PROXY` ekskluderinger. Caches konfiguration for 30'erne. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | #### SSE Streaming Pipeline @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Anmod om loggersessionsstruktur +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 applikationslag (`src/`) +### 4.7 Application Layer (`src/`) -| Katalog | Formål | -| ------------- | ---------------------------------------------------------------------------- | -| `src/app/` | Web-UI, API-ruter, Express-middleware, OAuth-tilbagekaldsbehandlere | -| `src/lib/` | Databaseadgang (`localDb.ts`, `usageDb.ts`), godkendelse, delt | -| `src/mitm/` | Man-in-the-middle proxy-værktøjer til at opsnappe udbydertrafik | -| `src/models/` | Databasemodeldefinitioner | -| `src/shared/` | Indpakninger omkring åben-sse-funktioner (udbyder, stream, fejl osv.) | -| `src/sse/` | SSE-slutpunktshandlere, der forbinder open-sse-biblioteket til Express-ruter | -| `src/store/` | Administration af applikationstilstand | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Bemærkelsesværdige API-ruter +#### Notable API Routes -| Rute | Metoder | Formål | -| --------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------ | -| `/api/provider-models` | GET/POST/SLET | CRUD til brugerdefinerede modeller pr. udbyder | -| `/api/models/catalog` | FÅ | Samlet katalog over alle modeller (chat, indlejring, billede, brugerdefineret) grupperet efter udbyder | -| `/api/settings/proxy` | GET/SETT/SLET | Hierarkisk udgående proxy-konfiguration (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Validerer proxy-forbindelse og returnerer offentlig IP/latency | -| `/v1/providers/[provider]/chat/completions` | POST | Dedikerede chat-afslutninger pr. udbyder med modelvalidering | -| `/v1/providers/[provider]/embeddings` | POST | Dedikerede indlejringer pr. udbyder med modelvalidering | -| `/v1/providers/[provider]/images/generations` | POST | Dedikeret billedgenerering pr. udbyder med modelvalidering | -| `/api/settings/ip-filter` | GET/PUT | Administration af IP-tilladelsesliste/blokeringsliste | -| `/api/settings/thinking-budget` | GET/PUT | Begrundelsestokens budgetkonfiguration (passthrough/auto/custom/adaptive) | -| `/api/settings/system-prompt` | GET/PUT | Global systemprompt-injektion for alle anmodninger | -| `/api/sessions` | FÅ | Aktiv sessionssporing og metrics | -| `/api/rate-limits` | FÅ | Satsgrænsestatus pr. konto | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Nøgledesignmønstre +## 5. Key Design Patterns -### 5.1 Hub-and-Speake-oversættelse +### 5.1 Hub-and-Spoke Translation -Alle formater oversættes gennem **OpenAI-format som hub**. Tilføjelse af en ny udbyder kræver kun at skrive **et par** af oversættere (til/fra OpenAI), ikke N par. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Eksekutørstrategimønster +### 5.2 Executor Strategy Pattern -Hver udbyder har en dedikeret eksekveringsklasse, der arver fra `BaseExecutor`. Fabrikken i `executors/index.ts` vælger den rigtige ved kørsel. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Selvregistrerende plugin-system +### 5.3 Self-Registering Plugin System -Oversættermoduler registrerer sig selv ved import via `register()`. Tilføjelse af en ny oversætter er blot at oprette en fil og importere den. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Account Fallback med eksponentiel backoff +### 5.4 Account Fallback with Exponential Backoff -Når en udbyder returnerer 429/401/500, kan systemet skifte til den næste konto ved at anvende eksponentielle nedkøling (1s → 2s → 4s → max 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Combo modelkæder +### 5.5 Combo Model Chains -En "combo" grupperer flere `provider/model` strenge. Hvis den første fejler, går du automatisk tilbage til den næste. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Stateful streaming-oversættelse +### 5.6 Stateful Streaming Translation -Svaroversættelse opretholder tilstand på tværs af SSE-chunks (tænkebloksporing, akkumulering af værktøjsopkald, indholdsblokindeksering) via `initState()`-mekanismen. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Sikkerhedsbuffer for brug +### 5.7 Usage Safety Buffer -En 2000-token buffer tilføjes til rapporteret brug for at forhindre klienter i at ramme kontekstvinduegrænser på grund af overhead fra systemprompter og formatoversættelse. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Understøttede formater +## 6. Supported Formats -| Format | Retning | Identifikator | -| ------------------------ | ----------- | ------------------ | -| OpenAI Chat fuldførelser | kilde + mål | `openai` | -| OpenAI Responses API | kilde + mål | `openai-responses` | -| Antropiske Claude | kilde + mål | `claude` | -| Google Gemini | kilde + mål | `gemini` | -| Google Gemini CLI | kun mål | `gemini-cli` | -| Antigravitation | kilde + mål | `antigravity` | -| AWS Kiro | kun mål | `kiro` | -| Markør | kun mål | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Understøttede udbydere +## 7. Supported Providers -| Udbyder | Auth metode | Eksekutør | Nøglebemærkninger | -| ------------------------ | ----------------------------- | --------------- | ----------------------------------------------- | -| Antropiske Claude | API-nøgle eller OAuth | Standard | Bruger `x-api-key` header | -| Google Gemini | API-nøgle eller OAuth | Standard | Bruger `x-goog-api-key` header | -| Google Gemini CLI | OAuth | GeminiCLI | Bruger `streamGenerateContent` slutpunkt | -| Antigravitation | OAuth | Antigravitation | Multi-URL fallback, tilpasset genforsøg parsing | -| OpenAI | API nøgle | Standard | Standard bærer auth | -| Codex | OAuth | Codex | Injicerer systeminstruktioner, styrer tænkning | -| GitHub Copilot | OAuth + Copilot-token | Github | Dobbelt token, VSCode-header-efterligning | -| Kiro (AWS) | AWS SSO OIDC eller Social | Kiro | Binær EventStream-parsing | -| Markør IDE | Kontrolsum auth | Markør | Protobuf-kodning, SHA-256 kontrolsummer | -| Qwen | OAuth | Standard | Standard auth | -| iFlow | OAuth (grundlæggende + bærer) | Standard | Dobbelt godkendelseshoved | -| OpenRouter | API nøgle | Standard | Standard bærer auth | -| GLM, Kimi, MiniMax | API nøgle | Standard | Claude-kompatibel, brug `x-api-key` | -| `openai-compatible-*` | API nøgle | Standard | Dynamisk: ethvert OpenAI-kompatibelt slutpunkt | -| `anthropic-compatible-*` | API nøgle | Standard | Dynamisk: ethvert Claude-kompatibelt slutpunkt | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Oversigt over dataflow +## 8. Data Flow Summary -### Streaminganmodning +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Ikke-streamende anmodning +### Non-Streaming Request ```mermaid flowchart LR diff --git a/docs/i18n/da/FEATURES.md b/docs/i18n/da/FEATURES.md index 4cf8ffc8d9..82cc73b67b 100644 --- a/docs/i18n/da/FEATURES.md +++ b/docs/i18n/da/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Dashboard Feature Gallery +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Visuel guide til hver sektion af OmniRoute-dashboardet. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Udbydere +## 🔌 Providers -Administrer AI-udbyderforbindelser: OAuth-udbydere (Claude Code, Codex, Gemini CLI), API-nøgleudbydere (Groq, DeepSeek, OpenRouter) og gratis udbydere (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Kombinationer +## 🎨 Combos -Opret modelrouting (model aliases, background task degradation)-kombinationer med 6 strategier: Fyld-først, round-robin, power-of-to-choices, tilfældig, mindst brugt og omkostningsoptimeret. Hver combo kæder flere modeller med automatisk fallback. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Analyse +## 📊 Analytics -Omfattende brugsanalyse med token-forbrug, omkostningsestimater, aktivitetsvarmekort, ugentlige distributionsdiagrammer og opdelinger pr. udbyder. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Systemsundhed +## 🏥 System Health -Overvågning i realtid: oppetid, hukommelse, version, latency percentiler (p50/p95/p99), cache-statistik og udbyderens afbrydertilstande. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Oversætterlegeplads +## 🔧 Translator Playground -Fire tilstande til fejlfinding af API-oversættelser: **Playground** (formatkonverter), **Chat Tester** (live-anmodninger), **Test Bench** (batchtest) og **Live Monitor** (streaming i realtid). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Indstillinger +## 🎮 Model Playground _(v2.0.9+)_ -Generelle indstillinger, systemlagring, backup-styring (eksport/import-database), udseende (mørk/lys-tilstand), sikkerhed (inkluderer API-endepunktsbeskyttelse og blokering af tilpasset udbyder), routing, modstandsdygtighed og avanceret konfiguration. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI-værktøjer +## 🔧 CLI Tools -Et-klik-konfiguration til AI-kodningsværktøjer: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code og Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Anmodningslogs +## 🤖 CLI Agents _(v2.0.11+)_ -Logning af anmodninger i realtid med filtrering efter udbyder, model, konto og API-nøgle. Viser statuskoder, tokenbrug, latenstid og svardetaljer. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API-endepunkt +## 🌐 API Endpoint -Dit forenede API-slutpunkt med kapacitetsopdeling: Chatfuldførelser, indlejringer, billedgenerering, omrangering, lydtransskription og registrerede API-nøgler. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/da/TROUBLESHOOTING.md b/docs/i18n/da/TROUBLESHOOTING.md index 795146b1df..120092d63c 100644 --- a/docs/i18n/da/TROUBLESHOOTING.md +++ b/docs/i18n/da/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Fejlfinding +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Almindelige problemer og løsninger til OmniRoute. +Common problems and solutions for OmniRoute. --- -## Hurtige rettelser +## Quick Fixes -| Problem | Løsning | -| -------------------------------------- | --------------------------------------------------------------------------- | -| Første login virker ikke | Tjek `INITIAL_PASSWORD` i `.env` (standard: `123456`) | -| Dashboard åbner ved forkert port | Sæt `PORT=20128` og `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Ingen anmodningslogfiler under `logs/` | Sæt `ENABLE_REQUEST_LOGS=true` | -| EACCES: tilladelse nægtet | Indstil `DATA_DIR=/path/to/writable/dir` til at tilsidesætte `~/.omniroute` | -| Routingstrategi gemmer ikke | Opdatering til v1.4.11+ (Zod-skemafix for indstillinger persistens) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Udbyderproblemer +## Provider Issues -### "Sprogmodellen leverede ikke beskeder" +### "Language model did not provide messages" -**Årsag:** Udbyderkvoten er opbrugt. +**Cause:** Provider quota exhausted. -**Ret:** +**Fix:** -1. Tjek dashboard kvotesporing -2. Brug en kombination med reserveniveauer -3. Skift til billigere/gratis niveau +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Satsbegrænsende +### Rate Limiting -**Årsag:** Abonnementskvoten er opbrugt. +**Cause:** Subscription quota exhausted. -**Ret:** +**Fix:** -- Tilføj reserve: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Brug GLM/MiniMax som billig backup +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth-token er udløbet +### OAuth Token Expired -OmniRoute opdaterer automatisk tokens. Hvis problemerne fortsætter: +OmniRoute auto-refreshes tokens. If issues persist: -1. Dashboard → Udbyder → Genopret forbindelse -2. Slet og tilføj udbyderforbindelsen igen +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Skyproblemer +## Cloud Issues -### Cloud Sync-fejl +### Cloud Sync Errors -1. Bekræft `BASE_URL` point til din løbeforekomst (f.eks. `http://localhost:20128`) -2. Bekræft `CLOUD_URL` punkter til dit cloud-endepunkt (f.eks. `https://omniroute.dev`) -3. Hold `NEXT_PUBLIC_*` værdier på linje med værdier på serversiden +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Returnerer 500 +### Cloud `stream=false` Returns 500 -**Symptom:** `Unexpected token 'd'...` på cloud-endepunkt til ikke-streamingopkald. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Årsag:** Upstream returnerer SSE-nyttelast, mens klienten forventer JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Løsning:** Brug `stream=true` til direkte skyopkald. Lokal kørselstid inkluderer SSE→JSON fallback. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud siger tilsluttet, men "Ugyldig API-nøgle" +### Cloud Says Connected but "Invalid API key" -1. Opret en ny nøgle fra det lokale dashboard (`/api/keys`) -2. Kør skysynkronisering: Aktiver sky → Synkroniser nu -3. Gamle/ikke-synkroniserede nøgler kan stadig returnere `401` på skyen +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Docker-problemer +## Docker Issues -### CLI-værktøj viser ikke installeret +### CLI Tool Shows Not Installed -1. Tjek runtime-felter: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. For bærbar tilstand: brug billedmål `runner-cli` (bundtede CLI'er) -3. For værtsmonteringstilstand: Indstil `CLI_EXTRA_PATHS` og monter værtsbin-mappen som skrivebeskyttet -4. Hvis `installed=true` og `runnable=false`: binær blev fundet, men helbredstjekket mislykkedes +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Hurtig runtime-validering +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Omkostningsproblemer +## Cost Issues -### Høje omkostninger +### High Costs -1. Tjek brugsstatistik i Dashboard → Brug -2. Skift primær model til GLM/MiniMax -3. Brug gratis niveau (Gemini CLI, iFlow) til ikke-kritiske opgaver -4. Indstil omkostningsbudgetter pr. API-nøgle: Dashboard → API-nøgler → Budget +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Fejlretning +## Debugging -### Aktiver anmodningslogfiler +### Enable Request Logs -Indstil `ENABLE_REQUEST_LOGS=true` i din `.env` fil. Logfiler vises under biblioteket `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Tjek udbyderens helbred +### Check Provider Health ```bash # Health dashboard @@ -120,100 +120,135 @@ curl http://localhost:20128/api/monitoring/health ### Runtime Storage -- Hovedtilstand: `${DATA_DIR}/db.json` (udbydere, kombinationer, aliaser, nøgler, indstillinger) -- Anvendelse: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Anmodningslogfiler: `/logs/...` (når `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Circuit Breaker Problemer +## Circuit Breaker Issues -### Udbyder sidder fast i ÅBEN tilstand +### Provider stuck in OPEN state -Når en udbyders afbryder er ÅBEN, blokeres anmodninger, indtil nedkølingen udløber. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Ret:** +**Fix:** -1. Gå til **Dashboard → Indstillinger → Resiliens** -2. Tjek afbryderkortet for den berørte udbyder -3. Klik på **Nulstil alle** for at rydde alle afbrydere, eller vent på, at nedkølingen udløber -4. Bekræft, at udbyderen faktisk er tilgængelig, før du nulstiller +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Udbyderen bliver ved med at udløse strømafbryderen +### Provider keeps tripping the circuit breaker -Hvis en udbyder gentagne gange går i ÅBEN tilstand: +If a provider repeatedly enters OPEN state: -1. Tjek **Dashboard → Health → Provider Health** for fejlmønsteret -2. Gå til **Indstillinger → Resiliens → Udbyderprofiler** og øg fejltærsklen -3. Tjek, om udbyderen har ændret API-grænser eller kræver gengodkendelse -4. Gennemgå latency-telemetri — høj latenstid kan forårsage timeout-baserede fejl +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problemer med lydtransskription +## Audio Transcription Issues -### "Ikke-understøttet model" fejl +### "Unsupported model" error -- Sørg for, at du bruger det korrekte præfiks: `deepgram/nova-3` eller `assemblyai/best` -- Bekræft, at udbyderen er tilsluttet i **Dashboard → Udbydere** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Transskription returnerer tom eller mislykkes +### Transcription returns empty or fails -- Tjek understøttede lydformater: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Bekræft filstørrelsen er inden for udbyderens grænser (typisk < 25 MB) -- Tjek gyldigheden af udbyderens API-nøgle på udbyderkortet +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Oversætter-fejlretning +## Translator Debugging -Brug **Dashboard → Oversætter** til at fejlfinde problemer med formatoversættelse: +Use **Dashboard → Translator** to debug format translation issues: -| Tilstand | Hvornår skal man bruge | -| ---------------- | --------------------------------------------------------------------------------------------------------------- | -| **Legeplads** | Sammenlign input/output-formater side om side — indsæt en mislykket anmodning for at se, hvordan den oversættes | -| **Chattester** | Send livebeskeder og inspicer den fulde anmodnings-/svarnyttelast inklusive overskrifter | -| **Testbænk** | Kør batchtest på tværs af formatkombinationer for at finde ud af, hvilke oversættelser der er brudte | -| **Live Monitor** | Se anmodningsflow i realtid for at fange periodiske oversættelsesproblemer | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Almindelige formatproblemer +### Common format issues -- **Tænke-tags vises ikke** — Tjek, om måludbyderen understøtter tænkning og indstilling af tænkebudget -- **Værktøjsopkald falder** — Nogle formatoversættelser kan fjerne ikke-understøttede felter; verificere i Playground-tilstand -- **Systemprompt mangler** — Claude og Gemini håndterer systemprompts forskelligt; kontrollere oversættelsesoutput -- **SDK returnerer rå streng i stedet for objekt** — Rettet i v1.1.0: Response Sanizer fjerner nu ikke-standardfelter (`x_groq`, `usage_breakdown` osv.), der forårsager OpenAI SDK Pydantic valideringsfejl -- **GLM/ERNIE afviser `system` rolle** — Rettet i v1.1.0: Rollenormalisering flettes automatisk systemmeddelelser ind i brugermeddelelser for inkompatible modeller -- **`developer` rolle ikke genkendt** — Rettet i v1.1.0: automatisk konverteret til `system` for ikke-OpenAI-udbydere -- **`json_schema` virker ikke med Gemini** — Rettet i v1.1.0: `response_format` er nu konverteret til Gemini's `responseMimeType` + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Resiliensindstillinger +## Resilience Settings -### Automatisk hastighedsgrænse udløses ikke +### Auto rate-limit not triggering -- Automatisk hastighedsgrænse gælder kun for API-nøgleudbydere (ikke OAuth/abonnement) -- Bekræft, at **Indstillinger → Modstandsdygtighed → Udbyderprofiler** har aktiveret automatisk satsgrænse -- Tjek, om udbyderen returnerer `429` statuskoder eller `Retry-After` overskrifter +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Tuning eksponentiel backoff +### Tuning exponential backoff -Udbyderprofiler understøtter disse indstillinger: +Provider profiles support these settings: -- **Base delay** — Indledende ventetid efter første fejl (standard: 1s) -- **Maksimal forsinkelse** — Maksimal ventetid (standard: 30s) -- **Multiplikator** — Hvor meget skal forsinkelsen øges pr. på hinanden følgende fejl (standard: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Anti-tordenbesætning +### Anti-thundering herd -Når mange samtidige anmodninger rammer en hastighedsbegrænset udbyder, bruger OmniRoute mutex + automatisk hastighedsbegrænsning til at serialisere anmodninger og forhindre kaskadefejl. Dette er automatisk for API-nøgleudbydere. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Stadig fast? +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub-problemer**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arkitektur**: Se [link](ARCHITECTURE.md) for interne detaljer -- **API-reference**: Se [link](API_REFERENCE.md) for alle endepunkter -- **Health Dashboard**: Tjek **Dashboard → Health** for systemstatus i realtid -- **Oversætter**: Brug **Dashboard → Oversætter** til at fejlsøge formatproblemer +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/da/USER_GUIDE.md b/docs/i18n/da/USER_GUIDE.md index 94fe3053a9..5a043224df 100644 --- a/docs/i18n/da/USER_GUIDE.md +++ b/docs/i18n/da/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Brugervejledning +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Komplet guide til konfiguration af udbydere, oprettelse af kombinationer, integration af CLI-værktøjer og implementering af OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Indholdsfortegnelse +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Komplet guide til konfiguration af udbydere, oprettelse af kombinationer, integr --- -## 💰 Prissætning på et øjeblik +## 💰 Pricing at a Glance -| Tier | Udbyder | Omkostninger | Kvote nulstilling | Bedst til | -| ----------------- | ----------------- | ------------------- | ------------------ | -------------------------- | -| **💳 ABONNEMENT** | Claude Code (Pro) | 20 USD/md. | 5 timer + ugentlig | Allerede abonneret | -| | Codex (Plus/Pro) | $20-200/md. | 5 timer + ugentlig | OpenAI-brugere | -| | Gemini CLI | **GRATIS** | 180K/md + 1K/dag | Alle sammen! | -| | GitHub Copilot | $10-19/md. | Månedlig | GitHub-brugere | -| **🔑 API NØGLE** | DeepSeek | Betal pr. brug | Ingen | Billig ræsonnement | -| | Groq | Betal pr. brug | Ingen | Ultrahurtig slutning | -| | xAI (Grok) | Betal pr. brug | Ingen | Grok 4 ræsonnement | -| | Mistral | Betal pr. brug | Ingen | EU-hostede modeller | -| | Forvirring | Betal pr. brug | Ingen | Søgeforøget | -| | Sammen AI | Betal pr. brug | Ingen | Open source-modeller | -| | Fyrværkeri AI | Betal pr. brug | Ingen | Fast FLUX billeder | -| | Cerebras | Betal pr. brug | Ingen | Wafer-skala hastighed | -| | Sammenhæng | Betal pr. brug | Ingen | Kommando R+ RAG | -| | NVIDIA NIM | Betal pr. brug | Ingen | Virksomhedsmodeller | -| **💰 BILLIG** | GLM-4.7 | 0,6 USD/1 mio. | Dagligt 10:00 | Budget backup | -| | MiniMax M2.1 | $0,2/1 mio. | 5-timers rullende | Billigste mulighed | -| | Kimi K2 | 9 USD/md. lejlighed | 10M tokens/md. | Forudsigelige omkostninger | -| **🆓 GRATIS** | iFlow | $0 | Ubegrænset | 8 modeller gratis | -| | Qwen | $0 | Ubegrænset | 3 modeller gratis | -| | Kiro | $0 | Ubegrænset | Claude gratis | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Pro-tip:** Start med Gemini CLI (180K gratis/måned) + iFlow (ubegrænset gratis) combo = $0 omkostninger! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- ## 🎯 Use Cases -### Case 1: "Jeg har Claude Pro-abonnement" +### Case 1: "I have Claude Pro subscription" -**Problem:** Kvoten udløber ubrugt, satsgrænser under tung kodning +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Case 2: "Jeg vil have nul omkostninger" +### Case 2: "I want zero cost" -**Problem:** Har ikke råd til abonnementer, har brug for pålidelig AI-kodning +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Case 3: "Jeg har brug for 24/7 kodning, ingen afbrydelser" +### Case 3: "I need 24/7 coding, no interruptions" -**Problem:** Deadlines, har ikke råd til nedetid +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Case 4: "Jeg vil have GRATIS AI i OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Problem:** Har brug for AI-assistent i beskedapps, helt gratis +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Udbyderopsætning +## 📖 Provider Setup -### 🔐 Abonnementsudbydere +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Prof tip:** Brug Opus til komplekse opgaver, Sonnet for hurtighed. OmniRoute sporer kvote pr. model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (GRATIS 180K/måned!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,7 +152,7 @@ Models: gc/gemini-2.5-pro ``` -**Bedste værdi:** Kæmpe gratis niveau! Brug dette før betalte niveauer. +**Best Value:** Huge free tier! Use this before paid tiers. #### GitHub Copilot @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Billige udbydere +### 💰 Cheap Providers -#### GLM-4.7 (Daglig nulstilling, $0,6/1 mio.) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Tilmeld dig: [Zhipu AI](https://open.bigmodel.cn/) -2. Hent API-nøgle fra Coding Plan -3. Dashboard → Tilføj API-nøgle: Udbyder: `glm`, API-nøgle: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Brug:** `glm/glm-4.7` — **Prof tip:** Kodningsplan tilbyder 3× kvote til 1/7 pris! Nulstil dagligt 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 timers nulstilling, $0,20/1 mio.) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Tilmeld dig: [MiniMax](https://www.minimax.io/) -2. Hent API-nøgle → Dashboard → Tilføj API-nøgle +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Brug:** `minimax/MiniMax-M2.1` — **Prof tip:** Billigste mulighed for lang sammenhæng (1M tokens)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/måned lejlighed) +#### Kimi K2 ($9/month flat) -1. Abonner: [Moonshot AI](https://platform.moonshot.ai/) -2. Hent API-nøgle → Dashboard → Tilføj API-nøgle +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Brug:** `kimi/kimi-latest` — **Prof tip:** Fast $9/måned for 10M tokens = $0,90/1M effektive omkostninger! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 GRATIS udbydere +### 🆓 FREE Providers -#### iFlow (8 GRATIS modeller) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 GRATIS modeller) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRATIS) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Kombinationer +## 🎨 Combos -### Eksempel 1: Maksimer abonnement → Billig backup +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Eksempel 2: Kun gratis (nul omkostninger) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI-integration +## 🔧 CLI Integration -### Markør IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -262,7 +262,7 @@ Settings → Models → Advanced: ### Claude Code -Rediger `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Rediger `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Rediger `~/.openclaw/openclaw.json`: } ``` -**Eller brug Dashboard:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Fortsæt / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Implementering +## 🚀 Deployment -### VPS-implementering +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -For værtsintegreret tilstand med CLI-binære filer, se Docker-sektionen i hoveddokumenterne. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Miljøvariabler +### Environment Variables -| Variabel | Standard | Beskrivelse | -| --------------------- | ------------------------------------ | ---------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signeringshemmelighed (**ændring i produktion**) | -| `INITIAL_PASSWORD` | `123456` | Første login-adgangskode | -| `DATA_DIR` | `~/.omniroute` | Datamappe (db, forbrug, logfiler) | -| `PORT` | ramme standard | Serviceport (`20128` i eksempler) | -| `HOSTNAME` | ramme standard | Bind vært (Docker er som standard `0.0.0.0`) | -| `NODE_ENV` | runtime default | Indstil `production` til implementering | -| `BASE_URL` | `http://localhost:20128` | Intern basis-URL på serversiden | -| `CLOUD_URL` | `https://omniroute.dev` | Base URL for slutpunkt for skysynkronisering | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC-hemmelighed for genererede API-nøgler | -| `REQUIRE_API_KEY` | `false` | Gennemtving Bearer API-nøgle på `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Aktiverer anmodnings-/svarlogs | -| `AUTH_COOKIE_SECURE` | `false` | Tving `Secure` auth-cookie (bag HTTPS omvendt proxy) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -For den fulde reference til miljøvariablen, se [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Tilgængelige modeller +## 📊 Available Models
-Se alle tilgængelige modeller +View all available models **Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — 0,6 USD/1 mio.: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $0,2/1 mio.: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,7 +460,7 @@ For den fulde reference til miljøvariablen, se [README](../README.md). **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Forvirring (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` **Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` @@ -409,7 +468,7 @@ For den fulde reference til miljøvariablen, se [README](../README.md). **Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Kohere (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ For den fulde reference til miljøvariablen, se [README](../README.md). --- -## 🧩 Avancerede funktioner +## 🧩 Advanced Features -### Brugerdefinerede modeller +### Custom Models -Tilføj ethvert model-id til enhver udbyder uden at vente på en appopdatering: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Eller brug Dashboard: **Udbydere → [Udbyder] → Brugerdefinerede modeller**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Dedikerede udbyderruter +### Dedicated Provider Routes -Rut anmodninger direkte til en specifik udbyder med modelvalidering: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Udbyderpræfikset tilføjes automatisk, hvis det mangler. Umatchede modeller returnerer `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Konfiguration af netværksproxy +### Network Proxy Configuration ```bash # Set global proxy @@ -463,7 +522,7 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Forrang:** Nøglespecifik → Kombinationsspecifik → Udbyderspecifik → Global → Miljø. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. ### Model Catalog API @@ -471,68 +530,68 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ curl http://localhost:20128/api/models/catalog ``` -Returnerer modeller grupperet efter udbyder med typer (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). ### Cloud Sync -- Synkroniser udbydere, kombinationer og indstillinger på tværs af enheder -- Automatisk baggrundssynkronisering med timeout + fejl-hurtig -- Foretrækker server-side `BASE_URL`/`CLOUD_URL` i produktion +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (fase 9) +### LLM Gateway Intelligence (Phase 9) -- **Semantisk cache** — Auto-cacher ikke-streaming, temperatur=0 svar (omgå med `X-OmniRoute-No-Cache: true`) -- **Anmod om idempotens** — Deduplikerer anmodninger inden for 5 sekunder via `Idempotency-Key` eller `X-Request-Id` header -- **Progress Tracking** — Tilmeld SSE `event: progress` begivenheder via `X-OmniRoute-Progress: true` header +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Oversætter Legeplads +### Translator Playground -Adgang via **Dashboard → Oversætter**. Fejlfind og visualiser, hvordan OmniRoute oversætter API-anmodninger mellem udbydere. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Tilstand | Formål | -| ---------------- | --------------------------------------------------------------------------------------------- | -| **Legeplads** | Vælg kilde-/målformater, indsæt en anmodning, og se det oversatte output med det samme | -| **Chattester** | Send live chatbeskeder gennem proxyen og inspicer den fulde anmodning/svar-cyklus | -| **Testbænk** | Kør batchtest på tværs af flere formatkombinationer for at bekræfte oversættelsens korrekthed | -| **Live Monitor** | Se oversættelser i realtid, mens anmodninger strømmer gennem proxyen | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Brugstilfælde:** +**Use cases:** -- Fejlfinding af, hvorfor en specifik klient/udbyder-kombination mislykkes -- Bekræft, at tankemærker, værktøjsopkald og systembeskeder oversættes korrekt -- Sammenlign formatforskelle mellem OpenAI, Claude, Gemini og Responses API-formater +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Routingstrategier +### Routing Strategies -Konfigurer via **Dashboard → Indstillinger → Routing**. +Configure via **Dashboard → Settings → Routing**. -| Strategi | Beskrivelse | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------- | -| **Fyld først** | Bruger konti i prioriteret rækkefølge — primær konto håndterer alle anmodninger, indtil de ikke er tilgængelige | -| **Round Robin** | Går gennem alle konti med en konfigurerbar sticky-grænse (standard: 3 opkald pr. konto) | -| **P2C (Power of Two Choices)** | Vælger 2 tilfældige konti og ruter til den sundere — balancerer belastning med bevidsthed om sundhed | -| **Tilfældig** | Vælger tilfældigt en konto for hver anmodning ved hjælp af Fisher-Yates shuffle | -| **Mindst brugt** | Ruter til kontoen med det ældste `lastUsedAt` tidsstempel, der fordeler trafikken jævnt | -| **Omkostningsoptimeret** | Ruter til kontoen med den laveste prioritetsværdi, optimerer til udbydere med laveste omkostninger | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Wildcard-modelaliaser +#### Wildcard Model Aliases -Opret jokertegnmønstre for at omdanne modelnavne: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Jokertegn understøtter `*` (alle tegn) og `?` (enkelt tegn). +Wildcards support `*` (any characters) and `?` (single character). -#### Fallback-kæder +#### Fallback Chains -Definer globale reservekæder, der gælder på tværs af alle anmodninger: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Modstandsdygtighed og strømafbrydere +### Resilience & Circuit Breakers -Konfigurer via **Dashboard → Indstillinger → Resiliens**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementerer modstandsdygtighed på udbyderniveau med fire komponenter: +OmniRoute implements provider-level resilience with four components: -1. **Udbyderprofiler** — Konfiguration pr. udbyder for: - - Fejltærskel (hvor mange fejl før åbning) - - Nedkølingsvarighed - - Følsomhed for registrering af hastighedsgrænse - - Eksponentielle backoff-parametre +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Redigerbare hastighedsgrænser** — Standardindstillinger på systemniveau, der kan konfigureres i dashboardet: - - **Requests Per Minute (RPM)** — Maksimale anmodninger pr. minut pr. konto - - **Min Time Between Requests** — Minimumsafstand i millisekunder mellem anmodninger - - **Maksimal samtidige anmodninger** — Maksimalt antal samtidige anmodninger pr. konto - - Klik på **Rediger** for at ændre, og klik derefter på **Gem** eller **Annuller**. Værdier bevarer via resilience API. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** — Sporer fejl pr. udbyder og åbner automatisk kredsløbet, når en tærskel er nået: - - **LUKKET** (Sund) — Anmodninger flyder normalt - - **ÅBEN** — Udbyderen er midlertidigt blokeret efter gentagne fejl - - **HALF_OPEN** — Tester, om udbyderen er genoprettet +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Politik og låste identifikatorer** — Viser strømafbryderstatus og låste identifikatorer med tvangsoplåsningsfunktion. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Automatisk registrering af hastighedsgrænse** — Overvåger `429` og `Retry-After` overskrifter for proaktivt at undgå at ramme udbyderens satsgrænser. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Prof tip:** Brug knappen **Nulstil alle** til at rydde alle strømafbrydere og nedkøling, når en udbyder kommer sig efter en fejl. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Databaseeksport/import +### Database Export / Import -Administrer databasesikkerhedskopier i **Dashboard → Indstillinger → System og lager**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Handling | Beskrivelse | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Eksporter database** | Downloader den aktuelle SQLite-database som en `.sqlite`-fil | -| **Eksporter alle (.tar.gz)** | Downloader et komplet backup-arkiv inklusive: database, indstillinger, kombinationer, udbyderforbindelser (ingen legitimationsoplysninger), API-nøglemetadata | -| **Importer database** | Upload en `.sqlite` fil for at erstatte den aktuelle database. Der oprettes automatisk en pre-import backup | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Importvalidering:** Den importerede fil er valideret for integritet (SQLite pragmatjek), påkrævede tabeller (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) og størrelse (maks. 100 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Brugstilfælde:** +**Use Cases:** -- Migrer OmniRoute mellem maskiner -- Opret eksterne sikkerhedskopier til katastrofegendannelse -- Del konfigurationer mellem teammedlemmer (eksporter alle → del arkiv) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Indstillinger Dashboard +### Settings Dashboard -Indstillingssiden er organiseret i 5 faner for nem navigation: +The settings page is organized into 5 tabs for easy navigation: -| Faneblad | Indhold | -| ------------- | --------------------------------------------------------------------------------------------------------- | -| **Sikkerhed** | Indstillinger for login/adgangskode, IP-adgangskontrol, API-godkendelse for `/models` og udbyderblokering | -| **Routing** | Global routingstrategi (6 muligheder), jokertegn-modelaliaser, reservekæder, combo-standarder | -| **Resiliens** | Udbyderprofiler, redigerbare hastighedsgrænser, strømafbryderstatus, politikker og låste identifikatorer | -| **AI** | Tænkende budgetkonfiguration, global systemprompt-injektion, prompt-cache-statistik | -| **Avanceret** | Global proxy-konfiguration (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Omkostninger og budgetstyring +### Costs & Budget Management -Adgang via **Dashboard → Omkostninger**. +Access via **Dashboard → Costs**. -| Faneblad | Formål | -| ---------- | -------------------------------------------------------------------------------------------------- | -| **Budget** | Indstil forbrugsgrænser pr. API-nøgle med daglige/ugentlige/månedlige budgetter og realtidssporing | -| **Priser** | Se og rediger modelprissætninger — pris pr. 1K input/output-tokens pr. udbyder | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Omkostningssporing:** Hver anmodning logger tokenbrug og beregner omkostninger ved hjælp af pristabellen. Se opdelinger i **Dashboard → Brug** efter udbyder, model og API-nøgle. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Lydtransskription +### Audio Transcription -OmniRoute understøtter lydtransskription via det OpenAI-kompatible slutpunkt: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Tilgængelige udbydere: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Understøttede lydformater: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Kombinationsbalanceringsstrategier +### Combo Balancing Strategies -Konfigurer balancering pr. kombination i **Dashboard → Combos → Opret/Rediger → Strategi**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategi | Beskrivelse | -| ------------------------ | ----------------------------------------------------------------------------- | -| **Round-Robin** | Roterer sekventielt gennem modeller | -| **Prioritet** | Prøver altid den første model; falder kun tilbage på fejl | -| **Tilfældig** | Vælger en tilfældig model fra kombinationen for hver anmodning | -| **Vægtet** | Ruter proportionalt baseret på tildelte vægte pr. model | -| **Mindst brugt** | Ruter til modellen med de færreste seneste anmodninger (bruger combo-metrics) | -| **Omkostningsoptimeret** | Ruter til den billigste tilgængelige model (bruger pristabel) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Globale kombinationsstandarder kan indstilles i **Dashboard → Indstillinger → Routing → Combo-standarder**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Sundhedsdashboard +### Health Dashboard -Adgang via **Dashboard → Health**. Oversigt over systemets tilstand i realtid med 6 kort: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Kort | Hvad det viser | -| --------------------- | --------------------------------------------------------- | -| **Systemstatus** | Oppetid, version, hukommelsesforbrug, datakatalog | -| **Udbydersundhed** | Per-leverandør afbrydertilstand (Lukket/Åben/Halv-Åben) | -| **Satsgrænser** | Aktive nedkølingsgrænser pr. konto med resterende tid | -| **Aktive lockouts** | Udbydere midlertidigt blokeret af lockout-politikken | -| **Signatur Cache** | Deduplikeringscache-statistikker (aktive nøgler, hitrate) | -| **Latency Telemetri** | p50/p95/p99 latenssammenlægning pr. udbyder | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Prof tip:** Sundhedssiden opdateres automatisk hvert 10. sekund. Brug afbryderkortet til at identificere, hvilke udbydere der oplever problemer. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/de/API_REFERENCE.md b/docs/i18n/de/API_REFERENCE.md index 9f6e28140f..b795722c11 100644 --- a/docs/i18n/de/API_REFERENCE.md +++ b/docs/i18n/de/API_REFERENCE.md @@ -1,12 +1,12 @@ -# API-Referenz +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Vollständige Referenz für alle OmniRoute-API-Endpunkte. +Complete reference for all OmniRoute API endpoints. --- -## Inhaltsverzeichnis +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Vollständige Referenz für alle OmniRoute-API-Endpunkte. --- -## Chat-Abschlüsse +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Benutzerdefinierte Header +### Custom Headers -| Kopfzeile | Richtung | Beschreibung | -| ------------------------ | -------- | -------------------------------------------- | -| `X-OmniRoute-No-Cache` | Anfrage | Auf `true` setzen, um den Cache zu umgehen | -| `X-OmniRoute-Progress` | Anfrage | Für Fortschrittsereignisse auf `true` setzen | -| `Idempotency-Key` | Anfrage | Dedup-Schlüssel (5-Sekunden-Fenster) | -| `X-Request-Id` | Anfrage | Alternativer Deduplizierungsschlüssel | -| `X-OmniRoute-Cache` | Antwort | `HIT` oder `MISS` (kein Streaming) | -| `X-OmniRoute-Idempotent` | Antwort | `true` wenn dedupliziert | -| `X-OmniRoute-Progress` | Antwort | `enabled` wenn Fortschrittsverfolgung auf | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Einbettungen +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Verfügbare Anbieter: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Bildgenerierung +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Verfügbare Anbieter: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Modelle auflisten +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Kompatibilitätsendpunkte +## Compatibility Endpoints -| Methode | Pfad | Formatieren | -| ------- | --------------------------- | --------------------------- | -| POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Anthropisch | -| POST | `/v1/responses` | OpenAI-Antworten | -| POST | `/v1/embeddings` | OpenAI | -| POST | `/v1/images/generations` | OpenAI | -| GET | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Anthropisch | -| GET | `/v1beta/models` | Zwillinge | -| POST | `/v1beta/models/{...path}` | Zwillinge generierenContent | -| POST | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Dedizierte Anbieterrouten +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Das Anbieterpräfix wird automatisch hinzugefügt, wenn es fehlt. Nicht übereinstimmende Modelle geben `400` zurück. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Semantischer Cache +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Antwortbeispiel: +Response example: ```json { @@ -162,154 +162,164 @@ Antwortbeispiel: --- -## Dashboard und Verwaltung +## Dashboard & Management -### Authentifizierung +### Authentication -| Endpunkt | Methode | Beschreibung | -| ----------------------------- | ------- | --------------------------------- | -| `/api/auth/login` | POST | Anmelden | -| `/api/auth/logout` | POST | Abmelden | -| `/api/settings/require-login` | GET/PUT | Anmeldung erforderlich umschalten | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Anbieterverwaltung +### Provider Management -| Endpunkt | Methode | Beschreibung | -| ---------------------------- | --------------- | -------------------------------- | -| `/api/providers` | GET/POST | Anbieter auflisten/anlegen | -| `/api/providers/[id]` | GET/PUT/DELETE | Einen Anbieter verwalten | -| `/api/providers/[id]/test` | POST | Provider-Verbindung testen | -| `/api/providers/[id]/models` | GET | Anbietermodelle auflisten | -| `/api/providers/validate` | POST | Anbieterkonfiguration validieren | -| `/api/provider-nodes*` | Verschiedene | Provider-Knotenverwaltung | -| `/api/provider-models` | GET/POST/DELETE | Kundenspezifische Modelle | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth-Flows +### OAuth Flows -| Endpunkt | Methode | Beschreibung | -| -------------------------------- | ------------ | -------------------------- | -| `/api/oauth/[provider]/[action]` | Verschiedene | Anbieterspezifisches OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Routing & Konfig +### Routing & Config -| Endpunkt | Methode | Beschreibung | -| --------------------- | ------------ | -------------------------------- | -| `/api/models/alias` | GET/POST | Modell-Aliase | -| `/api/models/catalog` | GET | Alle Modelle nach Anbieter + Typ | -| `/api/combos*` | Verschiedene | Combo-Management | -| `/api/keys*` | Verschiedene | API-Schlüsselverwaltung | -| `/api/pricing` | GET | Modellpreise | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Nutzung und Analyse +### Usage & Analytics -| Endpunkt | Methode | Beschreibung | -| --------------------------- | ------- | -------------------------------- | -| `/api/usage/history` | GET | Nutzungshistorie | -| `/api/usage/logs` | GET | Nutzungsprotokolle | -| `/api/usage/request-logs` | GET | Protokolle auf Anforderungsebene | -| `/api/usage/[connectionId]` | GET | Nutzung pro Verbindung | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Einstellungen +### Settings -| Endpunkt | Methode | Beschreibung | -| ------------------------------- | ------- | -------------------------------- | -| `/api/settings` | GET/PUT | Allgemeine Einstellungen | -| `/api/settings/proxy` | GET/PUT | Netzwerk-Proxy-Konfiguration | -| `/api/settings/proxy/test` | POST | Proxy-Verbindung testen | -| `/api/settings/ip-filter` | GET/PUT | IP-Zulassungs-/Blockierungsliste | -| `/api/settings/thinking-budget` | GET/PUT | Begründung des Token-Budgets | -| `/api/settings/system-prompt` | GET/PUT | Globale Systemaufforderung | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Überwachung +### Monitoring -| Endpunkt | Methode | Beschreibung | -| ------------------------ | ---------------- | --------------------------- | -| `/api/sessions` | GET | Aktive Sitzungsverfolgung | -| `/api/rate-limits` | GET | Tariflimits pro Konto | -| `/api/monitoring/health` | GET | Gesundheitscheck | -| `/api/cache` | ERHALTEN/LÖSCHEN | Cache-Statistiken / löschen | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Sichern und Exportieren/Importieren +### Backup & Export/Import -| Endpunkt | Methode | Beschreibung | -| --------------------------- | ------- | -------------------------------------------------------------- | -| `/api/db-backups` | GET | Verfügbare Backups auflisten | -| `/api/db-backups` | PUT | Erstellen Sie ein manuelles Backup | -| `/api/db-backups` | POST | Von einem bestimmten Backup wiederherstellen | -| `/api/db-backups/export` | GET | Datenbank als .sqlite-Datei herunterladen | -| `/api/db-backups/import` | POST | Laden Sie die .sqlite-Datei hoch, um die Datenbank zu ersetzen | -| `/api/db-backups/exportAll` | GET | Vollständiges Backup als .tar.gz-Archiv herunterladen | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Cloud-Synchronisierung +### Cloud Sync -| Endpunkt | Methode | Beschreibung | -| ---------------------- | ------------ | ------------------------------- | -| `/api/sync/cloud` | Verschiedene | Cloud-Synchronisierungsvorgänge | -| `/api/sync/initialize` | POST | Synchronisierung initialisieren | -| `/api/cloud/*` | Verschiedene | Cloud-Management | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI-Tools +### CLI Tools -| Endpunkt | Methode | Beschreibung | -| ---------------------------------- | ------- | ----------------------- | -| `/api/cli-tools/claude-settings` | GET | Claude CLI-Status | -| `/api/cli-tools/codex-settings` | GET | Codex-CLI-Status | -| `/api/cli-tools/droid-settings` | GET | Droid-CLI-Status | -| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI-Status | -| `/api/cli-tools/runtime/[toolId]` | GET | Generische CLI-Laufzeit | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Zu den CLI-Antworten gehören: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Belastbarkeit und Ratenbeschränkungen +### ACP Agents -| Endpunkt | Methode | Beschreibung | -| ----------------------- | ------- | -------------------------------------- | -| `/api/resilience` | GET/PUT | Resilienzprofile abrufen/aktualisieren | -| `/api/resilience/reset` | POST | Leistungsschalter zurücksetzen | -| `/api/rate-limits` | GET | Status der Ratenbegrenzung pro Konto | -| `/api/rate-limit` | GET | Konfiguration des globalen Ratenlimits | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Bewertungen +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Endpunkt | Methode | Beschreibung | -| ------------ | -------- | ---------------------------------------------------- | -| `/api/evals` | GET/POST | Evaluierungssuiten auflisten / Evaluierung ausführen | +### Resilience & Rate Limits -### Richtlinien +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Endpunkt | Methode | Beschreibung | -| --------------- | --------------- | ----------------------------- | -| `/api/policies` | GET/POST/DELETE | Routing-Richtlinien verwalten | +### Evals + +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | + +### Policies + +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | ### Compliance -| Endpunkt | Methode | Beschreibung | -| --------------------------- | ------- | -------------------------------------- | -| `/api/compliance/audit-log` | GET | Compliance-Audit-Protokoll (letztes N) | +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### v1beta (Gemini-kompatibel) +### v1beta (Gemini-Compatible) -| Endpunkt | Methode | Beschreibung | -| -------------------------- | ------- | ---------------------------------- | -| `/v1beta/models` | GET | Modelle im Gemini-Format auflisten | -| `/v1beta/models/{...path}` | POST | Gemini `generateContent` Endpunkt | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -Diese Endpunkte spiegeln das API-Format von Gemini für Kunden wider, die native Gemini SDK-Kompatibilität erwarten. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. -### Interne/System-APIs +### Internal / System APIs -| Endpunkt | Methode | Beschreibung | -| --------------- | ------- | ---------------------------------------------------------------------------- | -| `/api/init` | GET | Überprüfung der Anwendungsinitialisierung (wird beim ersten Start verwendet) | -| `/api/tags` | GET | Ollama-kompatible Modell-Tags (für Ollama-Clients) | -| `/api/restart` | POST | Ordentlichen Serverneustart auslösen | -| `/api/shutdown` | POST | Ordentliches Herunterfahren des Servers auslösen | +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | -> **Hinweis:** Diese Endpunkte werden intern vom System oder für die Ollama-Client-Kompatibilität verwendet. Sie werden normalerweise nicht von Endbenutzern aufgerufen. +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Audiotranskription +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transkribieren Sie Audiodateien mit Deepgram oder AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Anfrage:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Antwort:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Unterstützte Anbieter:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Unterstützte Formate:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Ollama-Kompatibilität +## Ollama Compatibility -Für Kunden, die das API-Format von Ollama verwenden: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Anfragen werden automatisch zwischen Ollama und internen Formaten übersetzt. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetrie +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Antwort:** +**Response:** ```json { @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Modellverfügbarkeit +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,26 +427,25 @@ Content-Type: application/json --- -## Bearbeitung der Anfrage +## Request Processing -1. Client sendet Anfrage an `/v1/*` -2. Route-Handler-Aufrufe `handleChat`, `handleEmbedding`, `handleAudioTranscription` oder `handleImageGeneration` -3. Modell wird aufgelöst (direkter Anbieter/Modell oder Alias/Kombination) -4. Aus der lokalen Datenbank ausgewählte Anmeldeinformationen mit Kontoverfügbarkeitsfilterung -5. Für Chat: `handleChatCore` – Formaterkennung, Übersetzung, Cache-Prüfung, Idempotenzprüfung -6. Der Executor des Anbieters sendet eine Upstream-Anfrage -7. Antwort zurück ins Client-Format übersetzt (Chat) oder unverändert zurückgegeben (Einbettungen/Bilder/Audio) -8. Nutzung/Protokollierung aufgezeichnet -9. Bei Fehlern gilt ein Fallback gemäß den Combo-Regeln +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Vollständige Architekturreferenz: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Authentifizierung +## Authentication -– Dashboard-Routen (`/dashboard/*`) verwenden das Cookie `auth_token` - -- Bei der Anmeldung wird der gespeicherte Passwort-Hash verwendet. Fallback auf `INITIAL_PASSWORD` -- `requireLogin` umschaltbar über `/api/settings/require-login` - – `/v1/*` Routen erfordern optional einen Bearer-API-Schlüssel, wenn `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/de/ARCHITECTURE.md b/docs/i18n/de/ARCHITECTURE.md index 5a94aeda7a..258d62df53 100644 --- a/docs/i18n/de/ARCHITECTURE.md +++ b/docs/i18n/de/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# OmniRoute-Architektur +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Letzte Aktualisierung: 18.02.2026_ +_Last updated: 2026-03-04_ -## Zusammenfassung +## Executive Summary -OmniRoute ist ein lokales KI-Routing-Gateway und Dashboard, das auf Next.js basiert. -Es bietet einen einzigen OpenAI-kompatiblen Endpunkt (`/v1/*`) und leitet den Datenverkehr über mehrere Upstream-Anbieter mit Übersetzung, Fallback, Token-Aktualisierung und Nutzungsverfolgung weiter. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Kernkompetenzen: +Core capabilities: -- OpenAI-kompatible API-Oberfläche für CLI/Tools (28 Anbieter) -- Anforderungs-/Antwortübersetzung über Anbieterformate hinweg -- Modell-Combo-Fallback (Multi-Modell-Sequenz) -- Fallback auf Kontoebene (mehrere Konten pro Anbieter) -- OAuth + API-Schlüssel-Provider-Verbindungsverwaltung -- Einbettungsgenerierung über `/v1/embeddings` (6 Anbieter, 9 Modelle) -- Bildgenerierung über `/v1/images/generations` (4 Anbieter, 9 Modelle) -- Denken Sie an Tag-Parsing (`...`) für Argumentationsmodelle -- Antwortbereinigung für strikte OpenAI SDK-Kompatibilität -- Rollennormalisierung (Entwickler→System, System→Benutzer) für anbieterübergreifende Kompatibilität -- Strukturierte Ausgabekonvertierung (json_schema → Gemini ResponseSchema) -- Lokale Persistenz für Anbieter, Schlüssel, Aliase, Kombinationen, Einstellungen, Preise -- Nutzungs-/Kostenverfolgung und Anforderungsprotokollierung -- Optionale Cloud-Synchronisierung für die Synchronisierung mehrerer Geräte/Status -- IP-Zulassungs-/Blockierungsliste für die API-Zugriffskontrolle -- Denken Sie an die Budgetverwaltung (Passthrough/Auto/Benutzerdefiniert/Adaptiv) -- Sofortige Injektion des globalen Systems -- Sitzungsverfolgung und Fingerabdruck -- Erweiterte Ratenbegrenzung pro Konto mit anbieterspezifischen Profilen -- Leistungsschaltermuster für die Ausfallsicherheit des Anbieters -- Donnernder Herdenschutz mit Mutex-Sperre - – Signaturbasierter Anforderungsdeduplizierungs-Cache -- Domänenschicht: Modellverfügbarkeit, Kostenregeln, Fallback-Richtlinie, Sperrrichtlinie -- Persistenz des Domänenstatus (SQLite-Durchschreibcache für Fallbacks, Budgets, Sperrungen, Leistungsschalter) -- Richtlinien-Engine für zentralisierte Anfrageauswertung (Sperrung → Budget → Fallback) -- Fordern Sie Telemetrie mit p50/p95/p99-Latenzaggregation an -- Korrelations-ID (X-Request-Id) für eine durchgängige Nachverfolgung -- Compliance-Audit-Protokollierung mit Opt-out pro API-Schlüssel -- Evaluierungsrahmen für die LLM-Qualitätssicherung -- Resilience-UI-Dashboard mit Echtzeit-Leistungsschalterstatus -- Modulare OAuth-Anbieter (12 einzelne Module unter `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Primäres Laufzeitmodell: +Primary runtime model: -– Next.js-App-Routen unter `src/app/api/*` implementieren sowohl Dashboard-APIs als auch Kompatibilitäts-APIs -– Ein gemeinsam genutzter SSE/Routing-Kern in `src/sse/*` + `open-sse/*` kümmert sich um die Ausführung, Übersetzung, Streaming, Fallback und Nutzung des Anbieters +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Umfang und Grenzen +## Scope and Boundaries -### Im Geltungsbereich +### In Scope -- Lokale Gateway-Laufzeit -- Dashboard-Verwaltungs-APIs -- Anbieterauthentifizierung und Token-Aktualisierung -- Fordern Sie Übersetzung und SSE-Streaming an -- Lokaler Status + Nutzungspersistenz -- Optionale Orchestrierung der Cloud-Synchronisierung +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Außerhalb des Gültigkeitsbereichs +### Out of Scope -- Cloud-Service-Implementierung hinter `NEXT_PUBLIC_CLOUD_URL` -- Anbieter-SLA/Kontrollebene außerhalb des lokalen Prozesses -- Externe CLI-Binärdateien selbst (Claude CLI, Codex CLI usw.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Systemkontext auf hoher Ebene +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,152 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Kernlaufzeitkomponenten +## Core Runtime Components -## 1) API und Routing-Ebene (Next.js App Routes) +## 1) API and Routing Layer (Next.js App Routes) -Hauptverzeichnisse: +Main directories: -- `src/app/api/v1/*` und `src/app/api/v1beta/*` für Kompatibilitäts-APIs - – `src/app/api/*` für Verwaltungs-/Konfigurations-APIs -- Nächste Umschreibungen in `next.config.mjs` ordnen `/v1/*` zu `/api/v1/*` zu +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Wichtige Kompatibilitätsrouten: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` – enthält benutzerdefinierte Modelle mit `custom: true` -- `src/app/api/v1/embeddings/route.ts` – Einbettungsgenerierung (6 Anbieter) -- `src/app/api/v1/images/generations/route.ts` — Bildgenerierung (4+ Anbieter inkl. Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` – dedizierter Chat pro Anbieter -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` – dedizierte Einbettungen pro Anbieter -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` – dedizierte Bilder pro Anbieter +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Verwaltungsdomänen: +Management domains: -- Authentifizierung/Einstellungen: `src/app/api/auth/*`, `src/app/api/settings/*` -- Anbieter/Verbindungen: `src/app/api/providers*` -- Anbieterknoten: `src/app/api/provider-nodes*` -- Benutzerdefinierte Modelle: `src/app/api/provider-models` (GET/POST/DELETE) -- Modellkatalog: `src/app/api/models/catalog` (GET) -- Proxy-Konfiguration: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Schlüssel/Aliase/Kombinationen/Preise: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Verwendung: `src/app/api/usage/*` -- Synchronisierung/Cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI-Tool-Helfer: `src/app/api/cli-tools/*` -- IP-Filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Denkbudget: `src/app/api/settings/thinking-budget` (GET/PUT) -- Systemaufforderung: `src/app/api/settings/system-prompt` (GET/PUT) -- Sitzungen: `src/app/api/sessions` (GET) -- Ratenlimits: `src/app/api/rate-limits` (GET) - – Belastbarkeit: `src/app/api/resilience` (GET/PATCH) – Anbieterprofile, Leistungsschalter, Ratengrenzzustand -- Resilienz-Reset: `src/app/api/resilience/reset` (POST) – Breaker + Abklingzeiten zurücksetzen -- Cache-Statistiken: `src/app/api/cache/stats` (GET/DELETE) -- Modellverfügbarkeit: `src/app/api/models/availability` (GET/POST) -- Telemetrie: `src/app/api/telemetry/summary` (GET) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) - Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback-Ketten: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance-Audit: `src/app/api/compliance/audit-log` (GET) -- Auswertungen: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Richtlinien: `src/app/api/policies` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Übersetzungskern +## 2) SSE + Translation Core -Hauptflussmodule: +Main flow modules: -- Eintrag: `src/sse/handlers/chat.ts` -- Kernorchestrierung: `open-sse/handlers/chatCore.ts` - – Anbieterausführungsadapter: `open-sse/executors/*` - – Formaterkennung/Anbieterkonfiguration: `open-sse/services/provider.ts` -- Modellanalyse/-auflösung: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Konto-Fallback-Logik: `open-sse/services/accountFallback.ts` -- Übersetzungsregister: `open-sse/translator/index.ts` -- Stream-Transformationen: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` - – Extraktion/Normalisierung der Nutzung: `open-sse/utils/usageTracking.ts` -- Think-Tag-Parser: `open-sse/utils/thinkTagParser.ts` -- Einbettungshandler: `open-sse/handlers/embeddings.ts` -- Anbieterregistrierung einbetten: `open-sse/config/embeddingRegistry.ts` -- Handler für die Bildgenerierung: `open-sse/handlers/imageGeneration.ts` -- Bildanbieter-Registrierung: `open-sse/config/imageRegistry.ts` - – Antwortbereinigung: `open-sse/handlers/responseSanitizer.ts` -- Rollennormalisierung: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Dienste (Geschäftslogik): +Services (business logic): -- Kontoauswahl/-bewertung: `open-sse/services/accountSelector.ts` -- Kontextlebenszyklusverwaltung: `open-sse/services/contextManager.ts` -- Durchsetzung des IP-Filters: `open-sse/services/ipFilter.ts` -- Sitzungsverfolgung: `open-sse/services/sessionManager.ts` - – Deduplizierung anfordern: `open-sse/services/signatureCache.ts` -- Eingabeaufforderung des Systems: `open-sse/services/systemPrompt.ts` -- Denkendes Budgetmanagement: `open-sse/services/thinkingBudget.ts` -- Wildcard-Modell-Routing: `open-sse/services/wildcardRouter.ts` -- Ratenlimitverwaltung: `open-sse/services/rateLimitManager.ts` -- Leistungsschalter: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Module der Domänenschicht: +Domain layer modules: -- Modellverfügbarkeit: `src/lib/domain/modelAvailability.ts` -- Kostenregeln/Budgets: `src/lib/domain/costRules.ts` -- Fallback-Richtlinie: `src/lib/domain/fallbackPolicy.ts` -- Combo-Resolver: `src/lib/domain/comboResolver.ts` -- Sperrrichtlinie: `src/lib/domain/lockoutPolicy.ts` - – Richtlinien-Engine: `src/domain/policyEngine.ts` – zentralisierte Sperrung → Budget → Fallback-Bewertung -- Fehlercodekatalog: `src/lib/domain/errorCodes.ts` -- Anforderungs-ID: `src/lib/domain/requestId.ts` - – Abrufzeitüberschreitung: `src/lib/domain/fetchTimeout.ts` -- Telemetrie anfordern: `src/lib/domain/requestTelemetry.ts` -- Compliance/Audit: `src/lib/domain/compliance/index.ts` - – Evaluierungsläufer: `src/lib/domain/evalRunner.ts` - – Domänenstatus-Persistenz: `src/lib/db/domainState.ts` – SQLite CRUD für Fallback-Ketten, Budgets, Kostenverlauf, Sperrstatus, Leistungsschalter +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth-Provider-Module (12 einzelne Dateien unter `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Registrierungsindex: `src/lib/oauth/providers/index.ts` -- Einzelne Anbieter: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` - – Thin Wrapper: `src/lib/oauth/providers.ts` – Re-Exporte aus einzelnen Modulen +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Persistenzschicht +## 3) Persistence Layer -Primärer Zustands-DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- Datei: `${DATA_DIR}/db.json` (oder `$XDG_CONFIG_HOME/omniroute/db.json`, wenn festgelegt, sonst `~/.omniroute/db.json`) -- Entitäten: ProviderConnections, ProviderNodes, ModelAliases, Combos, APIKeys, Einstellungen, Preise, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Nutzungs-DB: +Usage persistence: -- `src/lib/usageDb.ts` -- Dateien: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` - – Folgt derselben Basisverzeichnisrichtlinie wie `localDb` (`DATA_DIR`, dann `XDG_CONFIG_HOME/omniroute`, wenn festgelegt) -- zerlegt in fokussierte Untermodule: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present Domain State DB (SQLite): -– `src/lib/db/domainState.ts` – CRUD-Operationen für den Domänenstatus +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -- Tabellen (erstellt in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Write-Through-Cache-Muster: In-Memory-Maps sind zur Laufzeit maßgeblich; Mutationen werden synchron zu SQLite geschrieben; Der Status wird beim Kaltstart aus der DB wiederhergestellt +## 4) Auth + Security Surfaces -## 4) Authentifizierung + Sicherheitsoberflächen +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -- Dashboard-Cookie-Authentifizierung: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- API-Schlüsselgenerierung/-überprüfung: `src/shared/utils/apiKey.ts` - – Provider-Geheimnisse blieben in `providerConnections`-Einträgen bestehen -- Unterstützung für ausgehende Proxys über `open-sse/utils/proxyFetch.ts` (Env-Variablen) und `open-sse/utils/networkProxy.ts` (pro Anbieter oder global konfigurierbar) +## 5) Cloud Sync -## 5) Cloud-Synchronisierung +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -- Scheduler-Init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Periodische Aufgabe: `src/shared/services/cloudSyncScheduler.ts` -- Kontrollroute: `src/app/api/sync/cloud/route.ts` - -## Anforderungslebenszyklus (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -305,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Konto-Fallback-Flow +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -335,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Fallback-Entscheidungen werden von `open-sse/services/accountFallback.ts` mithilfe von Statuscodes und Fehlermeldungsheuristiken gesteuert. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth-Onboarding und Token-Aktualisierungslebenszyklus +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -367,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Die Aktualisierung während des Live-Verkehrs wird in `open-sse/handlers/chatCore.ts` über den Executor `refreshCredentials()` ausgeführt. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Cloud-Sync-Lebenszyklus (Aktivieren/Synchronisieren/Deaktivieren) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -401,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Die regelmäßige Synchronisierung wird durch `CloudSyncScheduler` ausgelöst, wenn die Cloud aktiviert ist. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Datenmodell und Speicherzuordnung +## Data Model and Storage Map ```mermaid erDiagram @@ -504,14 +504,14 @@ erDiagram } ``` -Physische Speicherdateien: +Physical storage files: -- Hauptstatus: `${DATA_DIR}/db.json` (oder `$XDG_CONFIG_HOME/omniroute/db.json`, wenn festgelegt, sonst `~/.omniroute/db.json`) -- Nutzungsstatistiken: `${DATA_DIR}/usage.json` -- Protokollzeilen anfordern: `${DATA_DIR}/log.txt` -- optionale Übersetzer-/Anfrage-Debug-Sitzungen: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Bereitstellungstopologie +## Deployment Topology ```mermaid flowchart LR @@ -523,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -542,242 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Modulzuordnung (entscheidungskritisch) +## Module Mapping (Decision-Critical) -### Routen- und API-Module +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: Kompatibilitäts-APIs -- `src/app/api/v1/providers/[provider]/*`: dedizierte Routen pro Anbieter (Chat, Einbettungen, Bilder) -- `src/app/api/providers*`: Anbieter CRUD, Validierung, Tests -- `src/app/api/provider-nodes*`: Benutzerdefinierte kompatible Knotenverwaltung -- `src/app/api/provider-models`: benutzerdefinierte Modellverwaltung (CRUD) -- `src/app/api/models/catalog`: vollständige Modellkatalog-API (alle Typen nach Anbieter gruppiert) - – `src/app/api/oauth/*`: OAuth/Gerätecodeflüsse -- `src/app/api/keys*`: Lebenszyklus des lokalen API-Schlüssels -- `src/app/api/models/alias`: Alias-Verwaltung -- `src/app/api/combos*`: Fallback-Kombinationsverwaltung -- `src/app/api/pricing`: Preisüberschreibungen für die Kostenberechnung -- `src/app/api/settings/proxy`: Proxy-Konfiguration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: Test der ausgehenden Proxy-Konnektivität (POST) -- `src/app/api/usage/*`: Nutzungs- und Protokoll-APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: Cloud-Synchronisierung und Cloud-orientierte Helfer -- `src/app/api/cli-tools/*`: lokale CLI-Konfigurationsschreiber/-prüfer -- `src/app/api/settings/ip-filter`: IP-Zulassungsliste/Blockliste (GET/PUT) -- `src/app/api/settings/thinking-budget`: Denk-Token-Budget-Konfiguration (GET/PUT) -- `src/app/api/settings/system-prompt`: globale Systemeingabeaufforderung (GET/PUT) -- `src/app/api/sessions`: aktive Sitzungsliste (GET) -- `src/app/api/rate-limits`: Status des Ratenlimits pro Konto (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Routing- und Ausführungskern +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: Anforderungsanalyse, Kombinationsbehandlung, Kontoauswahlschleife -- `open-sse/handlers/chatCore.ts`: Übersetzung, Executor-Versand, Wiederholungs-/Aktualisierungsbehandlung, Stream-Setup -- `open-sse/executors/*`: anbieterspezifisches Netzwerk- und Formatverhalten +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Übersetzungsregister und Formatkonverter +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: Übersetzerregistrierung und Orchestrierung -- Übersetzer anfordern: `open-sse/translator/request/*` -- Antwortübersetzer: `open-sse/translator/response/*` -- Formatkonstanten: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Beharrlichkeit +### Persistence -- `src/lib/localDb.ts`: persistente Konfiguration/Status -- `src/lib/usageDb.ts`: Nutzungsverlauf und fortlaufende Anforderungsprotokolle +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Provider Executor Coverage (Strategiemuster) +## Provider Executor Coverage (Strategy Pattern) -Jeder Anbieter verfügt über einen speziellen Executor, der `BaseExecutor` (in `open-sse/executors/base.ts`) erweitert und URL-Erstellung, Header-Konstruktion, Wiederholungsversuche mit exponentiellem Backoff, Hooks für die Aktualisierung von Anmeldeinformationen und die Orchestrierungsmethode `execute()` bereitstellt. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Testamentsvollstrecker | Anbieter(n) | Besondere Handhabung | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamische URL-/Header-Konfiguration pro Anbieter | -| `AntigravityExecutor` | Google Antigravitation | Benutzerdefinierte Projekt-/Sitzungs-IDs, Wiederholen nach dem Parsen | -| `CodexExecutor` | OpenAI-Codex | Fügt Systemanweisungen ein und erzwingt den Denkaufwand | -| `CursorExecutor` | Cursor-IDE | ConnectRPC-Protokoll, Protobuf-Kodierung, Anforderungssignatur über Prüfsumme | -| `GithubExecutor` | GitHub-Copilot | Copilot-Token-Aktualisierung, VSCode-imitierende Header | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream-Binärformat → SSE-Konvertierung | -| `GeminiCLIExecutor` | Gemini CLI | Aktualisierungszyklus des Google OAuth-Tokens | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Alle anderen Anbieter (einschließlich benutzerdefinierter kompatibler Knoten) verwenden `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Anbieterkompatibilitätsmatrix +## Provider Compatibility Matrix -| Anbieter | Formatieren | Authentifizierung | Stream | Nicht-Stream | Token-Aktualisierung | Nutzungs-API | -| ---------------- | ---------------- | ---------------------------- | ---------------- | ------------ | -------------------- | ------------------------------ | -| Claude | Claude | API-Schlüssel / OAuth | ✅ | ✅ | ✅ | ⚠️ Nur Administrator | -| Zwillinge | Zwillinge | API-Schlüssel / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud-Konsole | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud-Konsole | -| Antigravitation | Antigravitation | OAuth | ✅ | ✅ | ✅ | ✅ Vollständige Kontingent-API | -| OpenAI | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| Kodex | Openai-Antworten | OAuth | ✅ gezwungen | ❌ | ✅ | ✅ Tariflimits | -| GitHub-Copilot | openai | OAuth + Copilot-Token | ✅ | ✅ | ✅ | ✅ Kontingent-Snapshots | -| Cursor | Cursor | Benutzerdefinierte Prüfsumme | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Nutzungsbeschränkungen | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Auf Anfrage | -| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Auf Anfrage | -| OpenRouter | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | Claude | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| Ratlosigkeit | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| Zusammen KI | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| Feuerwerk KI | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| Großhirn | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| Kohärent | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API-Schlüssel | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Übersetzungsabdeckung im Format +## Format Translation Coverage -Zu den erkannten Quellformaten gehören: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Zu den Zielformaten gehören: +Target formats include: -- OpenAI-Chat/Antworten +- OpenAI chat/Responses - Claude -- Gemini/Gemini-CLI/Antigravity-Umschlag +- Gemini/Gemini-CLI/Antigravity envelope - Kiro - Cursor -Übersetzungen verwenden **OpenAI als Hub-Format** – alle Konvertierungen durchlaufen OpenAI als Zwischenformat: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Übersetzungen werden dynamisch basierend auf der Form der Quellnutzlast und dem Zielformat des Anbieters ausgewählt. +Translations are selected dynamically based on source payload shape and provider target format. -Zusätzliche Verarbeitungsebenen in der Übersetzungspipeline: +Additional processing layers in the translation pipeline: -- **Antwortbereinigung** – Entfernt nicht standardmäßige Felder aus Antworten im OpenAI-Format (sowohl Streaming als auch Nicht-Streaming), um eine strikte SDK-Konformität sicherzustellen -- **Rollennormalisierung** – Konvertiert `developer` → `system` für Nicht-OpenAI-Ziele; führt `system` → `user` für Modelle zusammen, die die Systemrolle ablehnen (GLM, ERNIE) -- **Think-Tag-Extraktion** – Analysiert `...`-Blöcke aus dem Inhalt in das Feld `reasoning_content` -- **Strukturierte Ausgabe** – Konvertiert OpenAI `response_format.json_schema` in Geminis `responseMimeType` + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Unterstützte API-Endpunkte +## Supported API Endpoints -| Endpunkt | Formatieren | Handler | -| -------------------------------------------------- | -------------------------- | ----------------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI-Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude-Nachrichten | Gleicher Handler (automatisch erkannt) | -| `POST /v1/responses` | OpenAI-Antworten | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI-Einbettungen | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Modellliste | API-Route | -| `POST /v1/images/generations` | OpenAI-Bilder | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Modellliste | API-Route | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI-Chat | Dedizierter pro Anbieter mit Modellvalidierung | -| `POST /v1/providers/{provider}/embeddings` | OpenAI-Einbettungen | Dedizierter pro Anbieter mit Modellvalidierung | -| `POST /v1/providers/{provider}/images/generations` | OpenAI-Bilder | Dedizierter pro Anbieter mit Modellvalidierung | -| `POST /v1/messages/count_tokens` | Claude Token Count | API-Route | -| `GET /v1/models` | Liste der OpenAI-Modelle | API-Route (Chat + Einbettung + Bild + benutzerdefinierte Modelle) | -| `GET /api/models/catalog` | Katalog | Alle Modelle gruppiert nach Anbieter + Typ | -| `POST /v1beta/models/*:streamGenerateContent` | Zwillinge heimisch | API-Route | -| `GET/PUT/DELETE /api/settings/proxy` | Proxy-Konfiguration | Netzwerk-Proxy-Konfiguration | -| `POST /api/settings/proxy/test` | Proxy-Konnektivität | Proxy-Zustands-/Konnektivitätstest-Endpunkt | -| `GET/POST/DELETE /api/provider-models` | Benutzerdefinierte Modelle | Benutzerdefinierte Modellverwaltung pro Anbieter | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Bypass-Handler +## Bypass Handler -Der Bypass-Handler (`open-sse/utils/bypassHandler.ts`) fängt bekannte „Wegwerf“-Anfragen von Claude CLI ab – Warmup-Pings, Titelextraktionen und Token-Zählungen – und gibt eine **falsche Antwort** zurück, ohne Upstream-Provider-Tokens zu verbrauchen. Dies wird nur ausgelöst, wenn `User-Agent` `claude-cli` enthält. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Logger-Pipeline anfordern +## Request Logger Pipeline -Der Anforderungslogger (`open-sse/utils/requestLogger.ts`) stellt eine 7-stufige Debug-Protokollierungspipeline bereit, die standardmäßig deaktiviert und über `ENABLE_REQUEST_LOGS=true` aktiviert ist: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Dateien werden für jede Anforderungssitzung in `/logs//` geschrieben. +Files are written to `/logs//` for each request session. -## Fehlermodi und Belastbarkeit +## Failure Modes and Resilience -## 1) Konto-/Anbieterverfügbarkeit +## 1) Account/Provider Availability -- Abklingzeit des Anbieterkontos bei vorübergehenden/Raten-/Authentifizierungsfehlern -- Konto-Fallback vor fehlgeschlagener Anfrage -- Combo-Modell-Fallback, wenn der aktuelle Modell-/Anbieterpfad erschöpft ist +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Token-Ablauf +## 2) Token Expiry -- Vorabprüfung und Aktualisierung mit erneutem Versuch für aktualisierbare Anbieter - – 401/403-Wiederholungsversuch nach Aktualisierungsversuch im Kernpfad +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Stream-Sicherheit +## 3) Stream Safety -- Trennungsfähiger Stream-Controller - – Übersetzungsstream mit End-of-Stream-Flush und `[DONE]`-Behandlung -- Fallback der Nutzungsschätzung, wenn Metadaten zur Anbieternutzung fehlen +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Verschlechterung der Cloud-Synchronisierung +## 4) Cloud Sync Degradation -– Synchronisierungsfehler werden angezeigt, die lokale Laufzeit wird jedoch fortgesetzt -– Der Scheduler verfügt über eine wiederholfähige Logik, aber die regelmäßige Ausführung ruft derzeit standardmäßig eine Einzelversuchssynchronisierung auf +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Datenintegrität +## 5) Data Integrity -- DB-Shape-Migration/Reparatur für fehlende Schlüssel -- Schutzmaßnahmen zum Zurücksetzen beschädigter JSON-Dateien für localDb und useDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Beobachtbarkeit und Betriebssignale +## Observability and Operational Signals -Quellen für die Laufzeitsichtbarkeit: +Runtime visibility sources: -– Konsolenprotokolle von `src/sse/utils/logger.ts` -– Nutzungsaggregate pro Anfrage in `usage.json` +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -- Statusprotokoll der Textanfrage in `log.txt` - – optionale Protokolle für tiefe Anfragen/Übersetzungen unter `logs/`, wenn `ENABLE_REQUEST_LOGS=true` - – Dashboard-Nutzungsendpunkte (`/api/usage/*`) für die UI-Nutzung +## Security-Sensitive Boundaries -## Sicherheitsrelevante Grenzen +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -– JWT-Geheimnis (`JWT_SECRET`) sichert die Überprüfung/Signierung von Dashboard-Sitzungscookies -– Der anfängliche Passwort-Fallback (`INITIAL_PASSWORD`, Standard `123456`) muss in echten Bereitstellungen überschrieben werden -– Das HMAC-Geheimnis des API-Schlüssels (`API_KEY_SECRET`) sichert das generierte lokale API-Schlüsselformat -– Anbietergeheimnisse (API-Schlüssel/Tokens) werden in der lokalen Datenbank gespeichert und sollten auf Dateisystemebene geschützt werden -– Cloud-Synchronisierungsendpunkte basieren auf der API-Schlüsselauthentifizierung und der Maschinen-ID-Semantik +## Environment and Runtime Matrix -## Umgebungs- und Laufzeitmatrix +Environment variables actively used by code: -Vom Code aktiv verwendete Umgebungsvariablen: +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -- App/Authentifizierung: `JWT_SECRET`, `INITIAL_PASSWORD` -- Speicher: `DATA_DIR` -- Kompatibles Knotenverhalten: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` - – Optionale Speicherbasisüberschreibung (Linux/macOS, wenn `DATA_DIR` nicht gesetzt ist): `XDG_CONFIG_HOME` -- Sicherheits-Hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Protokollierung: `ENABLE_REQUEST_LOGS` -- Synchronisierung/Cloud-URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Ausgehender Proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` und Varianten in Kleinbuchstaben -- SOCKS5-Funktionsflags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Plattform-/Laufzeithelfer (keine App-spezifische Konfiguration): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +## Known Architectural Notes -## Bekannte architektonische Hinweise +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -1. `usageDb` und `localDb` verwenden jetzt dieselbe Basisverzeichnisrichtlinie (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) mit der Migration älterer Dateien. -2. `/api/v1/route.ts` gibt eine statische Modellliste zurück und ist nicht die Hauptmodellquelle, die von `/v1/models` verwendet wird. -3. Der Anforderungslogger schreibt bei Aktivierung vollständige Header/Textkörper. Behandeln Sie das Protokollverzeichnis als vertraulich. -4. Das Cloud-Verhalten hängt vom korrekten `NEXT_PUBLIC_BASE_URL` und der Erreichbarkeit des Cloud-Endpunkts ab. -5. Das Verzeichnis `open-sse/` wird als `@omniroute/open-sse` **npm-Arbeitsbereichspaket** veröffentlicht. Der Quellcode importiert es über `@omniroute/open-sse/...` (aufgelöst durch Next.js `transpilePackages`). Dateipfade in diesem Dokument verwenden aus Konsistenzgründen weiterhin den Verzeichnisnamen `open-sse/`. -6. Diagramme im Dashboard verwenden **Recharts** (SVG-basiert) für zugängliche, interaktive Analysevisualisierungen (Modellnutzungs-Balkendiagramme, Anbieteraufschlüsselungstabellen mit Erfolgsquoten). -7. E2E-Tests verwenden **Playwright** (`tests/e2e/`) und werden über `npm run test:e2e` ausgeführt. Unit-Tests verwenden **Node.js Test Runner** (`tests/unit/`) und werden über `npm run test:plan3` ausgeführt. Der Quellcode unter `src/` ist **TypeScript** (`.ts`/`.tsx`); Der Arbeitsbereich `open-sse/` bleibt JavaScript (`.js`). -8. Die Einstellungsseite ist in 5 Registerkarten unterteilt: Sicherheit, Routing (6 globale Strategien: Fill-First, Round-Robin, P2C, Random, Least-Used, Cost-Optimized), Resilience (bearbeitbare Ratenlimits, Leistungsschalter, Richtlinien), AI (Thinking Budget, System Prompt, Prompt Cache), Advanced (Proxy). +## Operational Verification Checklist -## Checkliste zur Betriebsüberprüfung - -- Build aus Quelle: `npm run build` -- Docker-Image erstellen: `docker build -t omniroute .` -- Starten Sie den Dienst und überprüfen Sie: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` - – Die Basis-URL des CLI-Ziels sollte `http://:20128/v1` sein, wenn `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/de/CODEBASE_DOCUMENTATION.md b/docs/i18n/de/CODEBASE_DOCUMENTATION.md index fa00c886c7..303880c198 100644 --- a/docs/i18n/de/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/de/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute – Codebase-Dokumentation +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Eine umfassende, einsteigerfreundliche Anleitung zum Multi-Provider-KI-Proxy-Router **omniroute**. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Was ist Omniroute? +## 1. What Is omniroute? -Omniroute ist ein **Proxy-Router**, der zwischen KI-Clients (Claude CLI, Codex, Cursor IDE usw.) und KI-Anbietern (Anthropic, Google, OpenAI, AWS, GitHub usw.) sitzt. Es löst ein großes Problem: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Verschiedene KI-Clients sprechen unterschiedliche „Sprachen“ (API-Formate) und unterschiedliche KI-Anbieter erwarten auch unterschiedliche „Sprachen“.** Omniroute übersetzt automatisch zwischen ihnen. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Stellen Sie sich das wie einen Universalübersetzer bei den Vereinten Nationen vor: Jeder Delegierte kann jede Sprache sprechen, und der Übersetzer übersetzt sie für jeden anderen Delegierten. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Architekturübersicht +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Grundprinzip: Hub-and-Spoke-Übersetzung +### Core Principle: Hub-and-Spoke Translation -Die gesamte Formatübersetzung erfolgt über das **OpenAI-Format als Hub**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Das bedeutet, dass Sie nur **N Übersetzer** (einen pro Format) statt **N²** (jedes Paar) benötigen. +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Projektstruktur +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Aufschlüsselung nach Modulen +## 4. Module-by-Module Breakdown -### 4.1 Konfiguration (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -Die **Single Source of Truth** für die gesamte Anbieterkonfiguration. +The **single source of truth** for all provider configuration. -| Datei | Zweck | -| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS`-Objekt mit Basis-URLs, OAuth-Anmeldeinformationen (Standard), Headern und Standard-Systemaufforderungen für jeden Anbieter. Definiert außerdem `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` und `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Lädt externe Anmeldeinformationen von `data/provider-credentials.json` und führt sie über die fest codierten Standardeinstellungen in `PROVIDERS` zusammen. Hält Geheimnisse von der Quellcodeverwaltung fern und sorgt gleichzeitig für Abwärtskompatibilität. | -| `providerModels.ts` | Zentrale Modellregistrierung: Ordnet Anbieter-Aliase → Modell-IDs zu. Funktionen wie `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | In Codex-Anfragen eingefügte Systemanweisungen (Bearbeitungsbeschränkungen, Sandbox-Regeln, Genehmigungsrichtlinien). | -| `defaultThinkingSignature.ts` | Standardmäßige „denkende“ Signaturen für die Modelle Claude und Gemini. | -| `ollamaModels.ts` | Schemadefinition für lokale Ollama-Modelle (Name, Größe, Familie, Quantisierung). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Ladevorgang für Anmeldeinformationen +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Ausführende (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Ausführende kapseln **anbieterspezifische Logik** mithilfe des **Strategiemusters**. Jeder Executor überschreibt bei Bedarf Basismethoden. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Testamentsvollstrecker | Anbieter | Schlüsselspezialisierungen | -| ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Abstrakte Basis: URL-Erstellung, Header, Wiederholungslogik, Aktualisierung der Anmeldeinformationen | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generische OAuth-Token-Aktualisierung für Standardanbieter | -| `antigravity.ts` | Google Cloud-Code | Projekt-/Sitzungs-ID-Generierung, Multi-URL-Fallback, benutzerdefinierte Wiederholungsanalyse von Fehlermeldungen („Zurücksetzen nach 2h7m23s“) | -| `cursor.ts` | Cursor-IDE | **Am komplexesten**: SHA-256-Prüfsummenauthentifizierung, Protobuf-Anforderungskodierung, binäres EventStream → SSE-Antwortanalyse | -| `codex.ts` | OpenAI-Codex | Fügt Systemanweisungen ein, verwaltet Denkebenen und entfernt nicht unterstützte Parameter | -| `gemini-cli.ts` | Google Gemini-CLI | Benutzerdefinierte URL-Erstellung (`streamGenerateContent`), Google OAuth-Token-Aktualisierung | -| `github.ts` | GitHub-Copilot | Dual-Token-System (GitHub OAuth + Copilot-Token), VSCode-Header-Nachahmung | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream-Binäranalyse, AMZN-Ereignisrahmen, Token-Schätzung | -| `index.ts` | — | Factory: ordnet Anbieternamen → Executor-Klasse zu, mit Standard-Fallback | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Handler (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -Die **Orchestrierungsebene** – koordiniert Übersetzung, Ausführung, Streaming und Fehlerbehandlung. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Datei | Zweck | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Zentraler Orchestrator** (~600 Leitungen). Verarbeitet den gesamten Anforderungslebenszyklus: Formaterkennung → Übersetzung → Executor-Versand → Streaming-/Nicht-Streaming-Antwort → Token-Aktualisierung → Fehlerbehandlung → Nutzungsprotokollierung. | -| `responsesHandler.ts` | Adapter für die Antwort-API von OpenAI: Konvertiert das Antwortformat → Chat-Abschlüsse → sendet an `chatCore` → konvertiert SSE zurück in das Antwortformat. | -| `embeddings.ts` | Handler für die Einbettungsgenerierung: Löst Einbettungsmodell → Anbieter auf, sendet an die Anbieter-API und gibt eine OpenAI-kompatible Einbettungsantwort zurück. Unterstützt mehr als 6 Anbieter. | -| `imageGeneration.ts` | Bildgenerierungs-Handler: Löst Bildmodell → Anbieter auf, unterstützt OpenAI-kompatible, Gemini-Image- (Antigravity) und Fallback-Modi (Nebius). Gibt Base64- oder URL-Bilder zurück. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Anforderungslebenszyklus (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Dienste (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Geschäftslogik, die die Handler und Ausführenden unterstützt. +Business logic that supports the handlers and executors. -| Datei | Zweck | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Formaterkennung** (`detectFormat`): Analysiert die Struktur des Anfragetexts, um Claude/OpenAI/Gemini/Antigravity/Responses-Formate zu identifizieren (einschließlich `max_tokens`-Heuristik für Claude). Außerdem: URL-Erstellung, Header-Erstellung, Denken an die Konfigurationsnormalisierung. Unterstützt die dynamischen Anbieter `openai-compatible-*` und `anthropic-compatible-*`. | -| `model.ts` | Parsen von Modellzeichenfolgen (`claude/model-name` → `{provider: "claude", model: "model-name"}`), Alias-Auflösung mit Kollisionserkennung, Eingabebereinigung (weist Pfaddurchquerung/Kontrollzeichen zurück) und Auflösung von Modellinformationen mit asynchroner Alias-Getter-Unterstützung. | -| `accountFallback.ts` | Umgang mit Ratenlimits: exponentielles Backoff (1 s → 2 s → 4 s → max. 2 min), Verwaltung der Kontoabklingzeit, Fehlerklassifizierung (welche Fehler einen Fallback auslösen und welche nicht). | -| `tokenRefresh.ts` | OAuth-Token-Aktualisierung für **jeden Anbieter**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot Dual-Token), Kiro (AWS SSO OIDC + Social Auth). Beinhaltet In-Flight-Promise-Deduplizierungs-Cache und Wiederholungsversuche mit exponentiellem Backoff. | -| `combo.ts` | **Combo-Modelle**: Ketten von Fallback-Modellen. Wenn Modell A mit einem Fallback-fähigen Fehler ausfällt, versuchen Sie es mit Modell B, dann mit C usw. Gibt tatsächliche Upstream-Statuscodes zurück. | -| `usage.ts` | Ruft Kontingent-/Nutzungsdaten von Anbieter-APIs ab (GitHub Copilot-Kontingente, Antigravity-Modellkontingente, Codex-Ratenbegrenzungen, Kiro-Nutzungsaufschlüsselungen, Claude-Einstellungen). | -| `accountSelector.ts` | Intelligente Kontoauswahl mit Bewertungsalgorithmus: Berücksichtigt Priorität, Gesundheitsstatus, Round-Robin-Position und Cooldown-Status, um für jede Anfrage das optimale Konto auszuwählen. | -| `contextManager.ts` | Lebenszyklusverwaltung des Anforderungskontexts: Erstellt und verfolgt Kontextobjekte pro Anforderung mit Metadaten (Anforderungs-ID, Zeitstempel, Anbieterinformationen) zum Debuggen und Protokollieren. | -| `ipFilter.ts` | IP-basierte Zugriffskontrolle: Unterstützt die Modi „Zulassungsliste“ und „Blockliste“. Validiert die Client-IP anhand konfigurierter Regeln, bevor API-Anfragen verarbeitet werden. | -| `sessionManager.ts` | Sitzungsverfolgung mit Client-Fingerprinting: Verfolgt aktive Sitzungen mithilfe gehashter Client-IDs, überwacht die Anzahl der Anfragen und stellt Sitzungsmetriken bereit. | -| `signatureCache.ts` | Anforderungssignaturbasierter Deduplizierungscache: Verhindert doppelte Anforderungen, indem aktuelle Anforderungssignaturen zwischengespeichert werden und zwischengespeicherte Antworten für identische Anforderungen innerhalb eines Zeitfensters zurückgegeben werden. | -| `systemPrompt.ts` | Globale System-Prompt-Injektion: Stellt allen Anfragen eine konfigurierbare System-Prompt voran oder hängt sie an, mit Kompatibilitätsbehandlung pro Anbieter. | -| `thinkingBudget.ts` | Verwaltung des Reasoning-Token-Budgets: Unterstützt Passthrough-, Auto- (Strip-Thinking-Konfiguration), benutzerdefinierte (festes Budget) und adaptive (komplexitätsskalierte) Modi zur Steuerung von Thinking-/Argument-Tokens. | -| `wildcardRouter.ts` | Routing von Wildcard-Modellmustern: Löst Wildcard-Muster (z. B. `*/claude-*`) basierend auf Verfügbarkeit und Priorität in konkrete Anbieter/Modell-Paare auf. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Token-Aktualisierungsdeduplizierung +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Konto-Fallback-Zustandsmaschine +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Combo-Modellkette +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Übersetzer (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -Die **Formatübersetzungs-Engine** verwendet ein selbstregistrierendes Plugin-System. +The **format translation engine** using a self-registering plugin system. -#### Architektur +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Verzeichnis | Dateien | Beschreibung | -| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 Übersetzer | Konvertieren Sie Anforderungstexte zwischen Formaten. Jede Datei registriert sich beim Import über `register(from, to, fn)` selbst. | -| `response/` | 7 Übersetzer | Konvertieren Sie Streaming-Antwortblöcke zwischen Formaten. Behandelt SSE-Ereignistypen, Denkblockaden und Toolaufrufe. | -| `helpers/` | 6 Helfer | Gemeinsame Dienstprogramme: `claudeHelper` (Extraktion von Systemeingabeaufforderungen, Thinking-Konfiguration), `geminiHelper` (Zuordnung von Teilen/Inhalten), `openaiHelper` (Formatfilterung), `toolCallHelper` (ID-Generierung, Injektion fehlender Antworten), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Übersetzungs-Engine: `translateRequest()`, `translateResponse()`, Statusverwaltung, Registrierung. | -| `formats.ts` | — | Formatkonstanten: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Schlüsseldesign: Selbstregistrierende Plugins +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -397,17 +397,17 @@ import "./request/claude-to-openai.js"; // ← self-registers ### 4.6 Utils (`open-sse/utils/`) -| Datei | Zweck | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Erstellung von Fehlerantworten (OpenAI-kompatibles Format), Upstream-Fehleranalyse, Antigravity-Wiederholungszeit-Extraktion aus Fehlermeldungen, SSE-Fehler-Streaming. | -| `stream.ts` | **SSE Transform Stream** – die zentrale Streaming-Pipeline. Zwei Modi: `TRANSLATE` (Vollformatübersetzung) und `PASSTHROUGH` (Nutzung normalisieren + extrahieren). Verarbeitet Chunk-Pufferung, Nutzungsschätzung und Inhaltslängenverfolgung. Pro-Stream-Encoder-/Decoder-Instanzen vermeiden den gemeinsamen Status. | -| `streamHelpers.ts` | Low-Level-SSE-Dienstprogramme: `parseSSELine` (leerzeichentolerant), `hasValuableContent` (filtert leere Blöcke für OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (formatbewusste SSE-Serialisierung mit `perf_metrics`-Bereinigung). | -| `usageTracking.ts` | Extraktion der Token-Nutzung aus jedem Format (Claude/OpenAI/Gemini/Responses), Schätzung mit separaten Zeichen-pro-Token-Verhältnissen für Tools/Nachrichten, Pufferzugabe (2000 Token-Sicherheitsspielraum), formatspezifische Feldfilterung, Konsolenprotokollierung mit ANSI-Farben. | -| `requestLogger.ts` | Dateibasierte Anforderungsprotokollierung (Opt-in über `ENABLE_REQUEST_LOGS=true`). Erstellt Sitzungsordner mit nummerierten Dateien: `1_req_client.json` → `7_res_client.txt`. Alle E/A erfolgen asynchron (Fire-and-Forget). Maskiert sensible Header. | -| `bypassHandler.ts` | Fängt bestimmte Muster von Claude CLI ab (Titelextraktion, Aufwärmen, Zählung) und gibt gefälschte Antworten zurück, ohne einen Anbieter anzurufen. Unterstützt sowohl Streaming als auch Nicht-Streaming. Absichtlich auf den Claude-CLI-Bereich beschränkt. | -| `networkProxy.ts` | Löst die ausgehende Proxy-URL für einen bestimmten Anbieter mit der Priorität auf: anbieterspezifische Konfiguration → globale Konfiguration → Umgebungsvariablen (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Unterstützt `NO_PROXY`-Ausschlüsse. Speichert die Konfiguration 30 Sekunden lang im Cache. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### SSE-Streaming-Pipeline +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Logger-Sitzungsstruktur anfordern +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Anwendungsschicht (`src/`) +### 4.7 Application Layer (`src/`) -| Verzeichnis | Zweck | -| ------------- | ----------------------------------------------------------------------------------- | -| `src/app/` | Web-Benutzeroberfläche, API-Routen, Express-Middleware, OAuth-Callback-Handler | -| `src/lib/` | Datenbankzugriff (`localDb.ts`, `usageDb.ts`), Authentifizierung, gemeinsam genutzt | -| `src/mitm/` | Man-in-the-Middle-Proxy-Dienstprogramme zum Abfangen des Provider-Verkehrs | -| `src/models/` | Datenbankmodelldefinitionen | -| `src/shared/` | Wrapper um Open-SSE-Funktionen (Anbieter, Stream, Fehler usw.) | -| `src/sse/` | SSE-Endpunkthandler, die die open-sse-Bibliothek mit Express-Routen verbinden | -| `src/store/` | Anwendungsstatusverwaltung | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Bemerkenswerte API-Routen +#### Notable API Routes -| Route | Methoden | Zweck | -| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | GET/POST/DELETE | CRUD für benutzerdefinierte Modelle pro Anbieter | -| `/api/models/catalog` | GET | Aggregierter Katalog aller Modelle (Chat, Einbettung, Bild, benutzerdefiniert), gruppiert nach Anbieter | -| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchische ausgehende Proxy-Konfiguration (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Validiert die Proxy-Konnektivität und gibt öffentliche IP/Latenz zurück | -| `/v1/providers/[provider]/chat/completions` | POST | Dedizierte Chat-Abschlüsse pro Anbieter mit Modellvalidierung | -| `/v1/providers/[provider]/embeddings` | POST | Dedizierte Einbettungen pro Anbieter mit Modellvalidierung | -| `/v1/providers/[provider]/images/generations` | POST | Dedizierte Image-Generierung pro Anbieter mit Modellvalidierung | -| `/api/settings/ip-filter` | GET/PUT | Verwaltung von IP-Zulassungs-/Blockierungslisten | -| `/api/settings/thinking-budget` | GET/PUT | Konfiguration des Reasoning-Token-Budgets (Passthrough/Auto/Benutzerdefiniert/Adaptiv) | -| `/api/settings/system-prompt` | GET/PUT | Globale System-Prompt-Injektion für alle Anfragen | -| `/api/sessions` | GET | Aktive Sitzungsverfolgung und Metriken | -| `/api/rate-limits` | GET | Status der Ratenbegrenzung pro Konto | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Wichtige Designmuster +## 5. Key Design Patterns -### 5.1 Hub-and-Spoke-Übersetzung +### 5.1 Hub-and-Spoke Translation -Alle Formate werden über das **OpenAI-Format als Hub** übersetzt. Für das Hinzufügen eines neuen Anbieters ist nur das Schreiben von **einem Paar** Übersetzern (zu/von OpenAI) erforderlich, nicht von N Paaren. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Executor-Strategiemuster +### 5.2 Executor Strategy Pattern -Jeder Anbieter verfügt über eine dedizierte Executor-Klasse, die von `BaseExecutor` erbt. Die Factory in `executors/index.ts` wählt zur Laufzeit die richtige aus. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Selbstregistrierendes Plugin-System +### 5.3 Self-Registering Plugin System -Übersetzermodule registrieren sich beim Import über `register()`. Beim Hinzufügen eines neuen Übersetzers wird lediglich eine Datei erstellt und importiert. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Konto-Fallback mit exponentiellem Backoff +### 5.4 Account Fallback with Exponential Backoff -Wenn ein Anbieter 429/401/500 zurückgibt, kann das System zum nächsten Konto wechseln und dabei exponentielle Abklingzeiten anwenden (1 Sek. → 2 Sek. → 4 Sek. → max. 2 Min.). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Combo-Modellketten +### 5.5 Combo Model Chains -Eine „Kombination“ gruppiert mehrere `provider/model`-Strings. Wenn der erste fehlschlägt, wird automatisch auf den nächsten zurückgegriffen. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Stateful Streaming-Übersetzung +### 5.6 Stateful Streaming Translation -Die Antwortübersetzung behält den Status über SSE-Chunks hinweg bei (Nachverfolgung von Denkblöcken, Akkumulation von Toolaufrufen, Indizierung von Inhaltsblöcken) über den `initState()`-Mechanismus. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Nutzungssicherheitspuffer +### 5.7 Usage Safety Buffer -Der gemeldeten Nutzung wird ein 2000-Token-Puffer hinzugefügt, um zu verhindern, dass Clients aufgrund von Overhead durch Systemeingabeaufforderungen und Formatübersetzung die Kontextfenstergrenzen erreichen. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Unterstützte Formate +## 6. Supported Formats -| Formatieren | Richtung | Bezeichner | -| ---------------------- | ------------- | ------------------ | -| OpenAI-Chat-Abschlüsse | Quelle + Ziel | `openai` | -| OpenAI Responses API | Quelle + Ziel | `openai-responses` | -| Anthropischer Claude | Quelle + Ziel | `claude` | -| Google Gemini | Quelle + Ziel | `gemini` | -| Google Gemini-CLI | Nur Ziel | `gemini-cli` | -| Antigravitation | Quelle + Ziel | `antigravity` | -| AWS Kiro | Nur Ziel | `kiro` | -| Cursor | Nur Ziel | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Unterstützte Anbieter +## 7. Supported Providers -| Anbieter | Authentifizierungsmethode | Testamentsvollstrecker | Wichtige Anmerkungen | -| ------------------------ | --------------------------- | ---------------------- | ----------------------------------------------------------- | -| Anthropischer Claude | API-Schlüssel oder OAuth | Standard | Verwendet den Header `x-api-key` | -| Google Gemini | API-Schlüssel oder OAuth | Standard | Verwendet den Header `x-goog-api-key` | -| Google Gemini-CLI | OAuth | GeminiCLI | Verwendet den Endpunkt `streamGenerateContent` | -| Antigravitation | OAuth | Antigravitation | Multi-URL-Fallback, benutzerdefinierte Wiederholungsanalyse | -| OpenAI | API-Schlüssel | Standard | Standard Bearer-Authentifizierung | -| Kodex | OAuth | Kodex | Fügt Systemanweisungen ein, verwaltet das Denken | -| GitHub-Copilot | OAuth + Copilot-Token | Github | Dual-Token, VSCode-Header-Nachahmung | -| Kiro (AWS) | AWS SSO OIDC oder Social | Kiro | Binäres EventStream-Parsen | -| Cursor-IDE | Prüfsummenauthentifizierung | Cursor | Protobuf-Kodierung, SHA-256-Prüfsummen | -| Qwen | OAuth | Standard | Standardauthentifizierung | -| iFlow | OAuth (Basic + Bearer) | Standard | Dual-Auth-Header | -| OpenRouter | API-Schlüssel | Standard | Standard Bearer-Authentifizierung | -| GLM, Kimi, MiniMax | API-Schlüssel | Standard | Claude-kompatibel, verwenden Sie `x-api-key` | -| `openai-compatible-*` | API-Schlüssel | Standard | Dynamisch: jeder OpenAI-kompatible Endpunkt | -| `anthropic-compatible-*` | API-Schlüssel | Standard | Dynamisch: jeder Claude-kompatible Endpunkt | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Zusammenfassung des Datenflusses +## 8. Data Flow Summary -### Streaming-Anfrage +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Nicht-Streaming-Anfrage +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Bypass-Flow (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/de/FEATURES.md b/docs/i18n/de/FEATURES.md index 184b0866f4..82cc73b67b 100644 --- a/docs/i18n/de/FEATURES.md +++ b/docs/i18n/de/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute – Dashboard-Funktionsgalerie +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Visuelle Anleitung zu jedem Abschnitt des OmniRoute-Dashboards. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Anbieter +## 🔌 Providers -Verwalten Sie KI-Anbieterverbindungen: OAuth-Anbieter (Claude Code, Codex, Gemini CLI), API-Schlüsselanbieter (Groq, DeepSeek, OpenRouter) und kostenlose Anbieter (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Kombinationen +## 🎨 Combos -Erstellen Sie Modell-Routing-Kombinationen mit 6 Strategien: Fill-First, Round-Robin, Power-of-Two-Choices, Random, Least-Used und Cost-Optimized. Jede Combo verkettet mehrere Modelle mit automatischem Fallback. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Analytik +## 📊 Analytics -Umfassende Nutzungsanalysen mit Token-Verbrauch, Kostenschätzungen, Aktivitäts-Heatmaps, wöchentlichen Verteilungsdiagrammen und Aufschlüsselungen pro Anbieter. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Systemgesundheit +## 🏥 System Health -Echtzeitüberwachung: Betriebszeit, Speicher, Version, Latenzperzentile (p50/p95/p99), Cache-Statistiken und Leistungsschalterzustände des Anbieters. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Übersetzerspielplatz +## 🔧 Translator Playground -Vier Modi zum Debuggen von API-Übersetzungen: **Playground** (Formatkonverter), **Chat Tester** (Live-Anfragen), **Test Bench** (Batch-Tests) und **Live Monitor** (Echtzeit-Stream). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Einstellungen +## 🎮 Model Playground _(v2.0.9+)_ -Allgemeine Einstellungen, Systemspeicher, Backup-Management (Datenbank exportieren/importieren), Erscheinungsbild (Dunkel-/Hellmodus), Sicherheit (einschließlich API-Endpunktschutz und benutzerdefinierter Anbieterblockierung), Routing, Ausfallsicherheit und erweiterte Konfiguration. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI-Tools +## 🔧 CLI Tools -Ein-Klick-Konfiguration für KI-Codierungstools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code und Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Protokolle anfordern +## 🤖 CLI Agents _(v2.0.11+)_ -Echtzeit-Anfrageprotokollierung mit Filterung nach Anbieter, Modell, Konto und API-Schlüssel. Zeigt Statuscodes, Token-Nutzung, Latenz und Antwortdetails an. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API-Endpunkt +## 🌐 API Endpoint -Ihr einheitlicher API-Endpunkt mit Aufschlüsselung der Funktionen: Chat-Abschlüsse, Einbettungen, Bildgenerierung, Reranking, Audiotranskription und registrierte API-Schlüssel. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/de/TROUBLESHOOTING.md b/docs/i18n/de/TROUBLESHOOTING.md index 5f255c16ae..120092d63c 100644 --- a/docs/i18n/de/TROUBLESHOOTING.md +++ b/docs/i18n/de/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Fehlerbehebung +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Häufige Probleme und Lösungen für OmniRoute. +Common problems and solutions for OmniRoute. --- -## Schnelle Lösungen +## Quick Fixes -| Problem | Lösung | -| ------------------------------------------ | ------------------------------------------------------------------------ | ---------------- | -| Erster Login funktioniert nicht | Überprüfen Sie `INITIAL_PASSWORD` in `.env` (Standard: `123456`) | -| Dashboard wird am falschen Port geöffnet | Legen Sie `PORT=20128` und `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | fest | -| Keine Anforderungsprotokolle unter `logs/` | Setze `ENABLE_REQUEST_LOGS=true` | -| EACCES: Berechtigung verweigert | Legen Sie `DATA_DIR=/path/to/writable/dir` fest, um `~/.omniroute` | zu überschreiben | -| Routing-Strategie wird nicht gespeichert | Update auf v1.4.11+ (Zod-Schema-Korrektur für Einstellungspersistenz) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Anbieterprobleme +## Provider Issues -### „Sprachmodell hat keine Nachrichten bereitgestellt“ +### "Language model did not provide messages" -**Ursache:** Anbieterkontingent erschöpft. +**Cause:** Provider quota exhausted. **Fix:** -1. Überprüfen Sie den Quoten-Tracker im Dashboard -2. Verwenden Sie eine Kombination mit Fallback-Stufen -3. Wechseln Sie zum günstigeren/kostenlosen Tarif +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Ratenbegrenzung +### Rate Limiting -**Ursache:** Das Abonnementkontingent ist erschöpft. +**Cause:** Subscription quota exhausted. **Fix:** -- Fallback hinzufügen: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Verwenden Sie GLM/MiniMax als günstiges Backup +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth-Token abgelaufen +### OAuth Token Expired -OmniRoute aktualisiert Token automatisch. Wenn die Probleme weiterhin bestehen: +OmniRoute auto-refreshes tokens. If issues persist: -1. Dashboard → Anbieter → Erneut verbinden -2. Löschen Sie die Anbieterverbindung und fügen Sie sie erneut hinzu +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Cloud-Probleme +## Cloud Issues -### Cloud-Synchronisierungsfehler +### Cloud Sync Errors -1. Überprüfen Sie, ob `BASE_URL` auf Ihre laufende Instanz verweist (z. B. `http://localhost:20128`). -2. Überprüfen Sie, ob `CLOUD_URL` auf Ihren Cloud-Endpunkt verweist (z. B. `https://omniroute.dev`). -3. Halten Sie die Werte von `NEXT_PUBLIC_*` an den serverseitigen Werten ausgerichtet +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Gibt 500 zurück +### Cloud `stream=false` Returns 500 -**Symptom:** `Unexpected token 'd'...` am Cloud-Endpunkt für Nicht-Streaming-Anrufe. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Ursache:** Upstream gibt SSE-Nutzdaten zurück, während der Client JSON erwartet. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Problemumgehung:** Verwenden Sie `stream=true` für Cloud-Direktaufrufe. Die lokale Laufzeit umfasst SSE→JSON-Fallback. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud sagt verbunden, aber „Ungültiger API-Schlüssel“ +### Cloud Says Connected but "Invalid API key" -1. Erstellen Sie einen neuen Schlüssel aus dem lokalen Dashboard (`/api/keys`). -2. Führen Sie die Cloud-Synchronisierung aus: Cloud aktivieren → Jetzt synchronisieren -3. Alte/nicht synchronisierte Schlüssel können weiterhin `401` in der Cloud zurückgeben +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Docker-Probleme +## Docker Issues -### CLI-Tool wird als „Nicht installiert“ angezeigt +### CLI Tool Shows Not Installed -1. Laufzeitfelder prüfen: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Für den portablen Modus: Bildziel `runner-cli` verwenden (gebündelte CLIs) -3. Für den Host-Mount-Modus: Legen Sie `CLI_EXTRA_PATHS` fest und mounten Sie das Host-Bin-Verzeichnis als schreibgeschützt -4. Wenn `installed=true` und `runnable=false`: Binärdatei gefunden wurde, die Integritätsprüfung jedoch fehlgeschlagen ist +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Schnelle Laufzeitvalidierung +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Kostenprobleme +## Cost Issues -### Hohe Kosten +### High Costs -1. Überprüfen Sie die Nutzungsstatistiken im Dashboard → Nutzung -2. Primärmodell auf GLM/MiniMax umstellen -3. Nutzen Sie das kostenlose Kontingent (Gemini CLI, iFlow) für unkritische Aufgaben -4. Legen Sie Kostenbudgets pro API-Schlüssel fest: Dashboard → API-Schlüssel → Budget +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Debuggen +## Debugging -### Anforderungsprotokolle aktivieren +### Enable Request Logs -Legen Sie `ENABLE_REQUEST_LOGS=true` in Ihrer `.env`-Datei fest. Protokolle werden im Verzeichnis `logs/` angezeigt. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Überprüfen Sie den Zustand des Anbieters +### Check Provider Health ```bash # Health dashboard @@ -118,104 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Laufzeitspeicher +### Runtime Storage -- Hauptstatus: `${DATA_DIR}/db.json` (Anbieter, Combos, Aliase, Schlüssel, Einstellungen) -- Verwendung: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` - – Anforderungsprotokolle: `/logs/...` (wenn `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Probleme mit Leistungsschaltern +## Circuit Breaker Issues -### Provider bleibt im OPEN-Zustand hängen +### Provider stuck in OPEN state -Wenn der Leistungsschalter eines Anbieters OFFEN ist, werden Anfragen blockiert, bis die Abklingzeit abgelaufen ist. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. **Fix:** -1. Gehen Sie zu **Dashboard → Einstellungen → Resilienz** -2. Überprüfen Sie die Leistungsschalterkarte des betroffenen Anbieters -3. Klicken Sie auf **Alle zurücksetzen**, um alle Unterbrecher zu löschen, oder warten Sie, bis die Abklingzeit abgelaufen ist -4. Stellen Sie vor dem Zurücksetzen sicher, dass der Anbieter tatsächlich verfügbar ist +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Der Anbieter löst weiterhin den Schutzschalter aus +### Provider keeps tripping the circuit breaker -Wenn ein Anbieter wiederholt in den OPEN-Zustand wechselt: +If a provider repeatedly enters OPEN state: -1. Überprüfen Sie **Dashboard → Health → Provider Health** auf das Fehlermuster -2. Gehen Sie zu **Einstellungen → Ausfallsicherheit → Anbieterprofile** und erhöhen Sie den Fehlerschwellenwert -3. Überprüfen Sie, ob der Anbieter die API-Grenzwerte geändert hat oder eine erneute Authentifizierung erfordert -4. Überprüfen Sie die Latenz-Telemetrie – hohe Latenz kann zu zeitüberschreitungsbedingten Fehlern führen +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Probleme mit der Audiotranskription +## Audio Transcription Issues -### Fehler „Nicht unterstütztes Modell“. +### "Unsupported model" error -– Stellen Sie sicher, dass Sie das richtige Präfix verwenden: `deepgram/nova-3` oder `assemblyai/best` +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -- Überprüfen Sie, ob der Anbieter unter **Dashboard → Anbieter** verbunden ist. +### Transcription returns empty or fails -### Die Transkription ist leer oder schlägt fehl - -- Überprüfen Sie die unterstützten Audioformate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Stellen Sie sicher, dass die Dateigröße innerhalb der Anbietergrenzen liegt (normalerweise < 25 MB). -- Überprüfen Sie die Gültigkeit des API-Schlüssels des Anbieters auf der Anbieterkarte +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Übersetzer-Debugging +## Translator Debugging -Verwenden Sie **Dashboard → Übersetzer**, um Formatübersetzungsprobleme zu beheben: +Use **Dashboard → Translator** to debug format translation issues: -| Modus | Wann zu verwenden | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| **Spielplatz** | Vergleichen Sie Eingabe-/Ausgabeformate nebeneinander – fügen Sie eine fehlgeschlagene Anfrage ein, um zu sehen, wie sie übersetzt wird | -| **Chat-Tester** | Senden Sie Live-Nachrichten und überprüfen Sie die vollständige Anfrage-/Antwort-Nutzlast einschließlich Header | -| **Prüfstand** | Führen Sie Stapeltests über Formatkombinationen hinweg durch, um herauszufinden, welche Übersetzungen fehlerhaft sind | -| **Live-Monitor** | Beobachten Sie den Anfragefluss in Echtzeit, um zeitweise auftretende Übersetzungsprobleme zu erkennen | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Häufige Formatprobleme +### Common format issues -- **Thinking-Tags werden nicht angezeigt** – Überprüfen Sie, ob der Zielanbieter Thinking und die Einstellung des Thinking-Budgets unterstützt -- **Tool-Aufrufe löschen** – Bei einigen Formatübersetzungen werden möglicherweise nicht unterstützte Felder entfernt. im Playground-Modus überprüfen -- **Systemaufforderung fehlt** – Claude und Gemini gehen unterschiedlich mit Systemaufforderungen um; Überprüfen Sie die Übersetzungsausgabe -- **SDK gibt Rohzeichenfolge anstelle von Objekt zurück** – In Version 1.1.0 behoben: Antwortbereinigung entfernt jetzt nicht standardmäßige Felder (`x_groq`, `usage_breakdown` usw.), die zu OpenAI SDK Pydantic-Validierungsfehlern führen -- **GLM/ERNIE lehnt die Rolle `system` ab** – In Version 1.1.0 behoben: Der Rollennormalisierer führt automatisch Systemnachrichten in Benutzernachrichten für inkompatible Modelle zusammen -- **`developer` Rolle nicht erkannt** – In v1.1.0 behoben: automatisch in `system` für Nicht-OpenAI-Anbieter konvertiert -- **`json_schema` funktioniert nicht mit Gemini** – In v1.1.0 behoben: `response_format` wird jetzt in Geminis `responseMimeType` + `responseSchema` konvertiert +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Resilienzeinstellungen +## Resilience Settings -### Automatische Ratenbegrenzung wird nicht ausgelöst +### Auto rate-limit not triggering -– Die automatische Ratenbegrenzung gilt nur für API-Schlüsselanbieter (nicht OAuth/Abonnement). +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -- Überprüfen Sie, ob in **Einstellungen → Ausfallsicherheit → Anbieterprofile** die automatische Ratenbegrenzung aktiviert ist - – Überprüfen Sie, ob der Anbieter Statuscodes `429` oder Header `Retry-After` zurückgibt +### Tuning exponential backoff -### Optimierung des exponentiellen Backoffs +Provider profiles support these settings: -Anbieterprofile unterstützen diese Einstellungen: +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -- **Basisverzögerung** – Anfängliche Wartezeit nach dem ersten Fehler (Standard: 1 s) -- **Max. Verzögerung** – Maximale Wartezeitobergrenze (Standard: 30 s) -- **Multiplikator** – Wie viel Verzögerung pro aufeinanderfolgendem Fehler erhöht werden soll (Standard: 2x) +### Anti-thundering herd -### Anti-donnernde Herde - -Wenn viele gleichzeitige Anfragen einen Anbieter mit begrenzter Rate treffen, verwendet OmniRoute Mutex + automatische Ratenbegrenzung, um Anfragen zu serialisieren und kaskadierende Fehler zu verhindern. Dies geschieht automatisch für API-Schlüsselanbieter. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Immer noch nicht weitergekommen? +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub-Probleme**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architektur**: Interne Details finden Sie unter [link](ARCHITECTURE.md) -- **API-Referenz**: Siehe [link](API_REFERENCE.md) für alle Endpunkte -- **Gesundheits-Dashboard**: Überprüfen Sie **Dashboard → Gesundheit** auf den Echtzeit-Systemstatus -- **Übersetzer**: Verwenden Sie **Dashboard → Übersetzer**, um Formatprobleme zu beheben +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/de/USER_GUIDE.md b/docs/i18n/de/USER_GUIDE.md index efd829b32e..5a043224df 100644 --- a/docs/i18n/de/USER_GUIDE.md +++ b/docs/i18n/de/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Benutzerhandbuch +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Vollständiger Leitfaden zum Konfigurieren von Anbietern, Erstellen von Kombinationen, Integrieren von CLI-Tools und Bereitstellen von OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Inhaltsverzeichnis +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Vollständiger Leitfaden zum Konfigurieren von Anbietern, Erstellen von Kombinat --- -## 💰 Preise im Überblick +## 💰 Pricing at a Glance -| Stufe | Anbieter | Kosten | Kontingent zurücksetzen | Am besten für | -| -------------------- | ----------------- | --------------------- | ------------------------- | ------------------------------- | -| **💳 ABO** | Claude Code (Pro) | 20 $/Monat | 5h + wöchentlich | Bereits abonniert | -| | Codex (Plus/Pro) | 20–200 $/Monat | 5h + wöchentlich | OpenAI-Benutzer | -| | Gemini CLI | **KOSTENLOS** | 180.000/Monat + 1.000/Tag | Alle! | -| | GitHub-Copilot | 10–19 $/Monat | Monatlich | GitHub-Benutzer | -| **🔑 API-SCHLÜSSEL** | DeepSeek | Bezahlung pro Nutzung | Keine | Billiges Denken | -| | Groq | Bezahlung pro Nutzung | Keine | Ultraschnelle Inferenz | -| | xAI (Grok) | Bezahlung pro Nutzung | Keine | Grok 4 Argumentation | -| | Mistral | Bezahlung pro Nutzung | Keine | In der EU gehostete Modelle | -| | Ratlosigkeit | Bezahlung pro Nutzung | Keine | Sucherweitert | -| | Zusammen KI | Bezahlung pro Nutzung | Keine | Open-Source-Modelle | -| | Feuerwerk KI | Bezahlung pro Nutzung | Keine | Schnelle FLUX-Bilder | -| | Großhirn | Bezahlung pro Nutzung | Keine | Geschwindigkeit im Wafermaßstab | -| | Kohärent | Bezahlung pro Nutzung | Keine | Befehl R+ RAG | -| | NVIDIA NIM | Bezahlung pro Nutzung | Keine | Unternehmensmodelle | -| **💰 GÜNSTIG** | GLM-4.7 | 0,6 $/1 Mio. | Täglich 10 Uhr | Budgetsicherung | -| | MiniMax M2.1 | 0,2 $/1 Mio. | 5-Stunden-Rollen | Günstigste Option | -| | Kimi K2 | $9/Monat pauschal | 10 Millionen Token/Monat | Vorhersehbare Kosten | -| **🆓 KOSTENLOS** | iFlow | $0 | Unbegrenzt | 8 Modelle kostenlos | -| | Qwen | $0 | Unbegrenzt | 3 Modelle kostenlos | -| | Kiro | $0 | Unbegrenzt | Claude frei | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Profi-Tipp:** Beginnen Sie mit der Kombination Gemini CLI (180.000 kostenlos/Monat) + iFlow (unbegrenzt kostenlos) = 0 $ Kosten! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Anwendungsfälle +## 🎯 Use Cases -### Fall 1: „Ich habe ein Claude Pro-Abonnement“ +### Case 1: "I have Claude Pro subscription" -**Problem:** Kontingent läuft ungenutzt ab, Ratenbegrenzungen bei intensiver Codierung +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Fall 2: „Ich möchte Nullkosten“ +### Case 2: "I want zero cost" -**Problem:** Ich kann mir keine Abonnements leisten und brauche zuverlässige KI-Codierung +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Fall 3: „Ich brauche 24/7-Codierung, keine Unterbrechungen“ +### Case 3: "I need 24/7 coding, no interruptions" -**Problem:** Fristen, ich kann mir Ausfallzeiten nicht leisten +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Fall 4: „Ich möchte KOSTENLOSE KI in OpenClaw“ +### Case 4: "I want FREE AI in OpenClaw" -**Problem:** Benötigen Sie einen KI-Assistenten in Messaging-Apps, völlig kostenlos +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Anbieter-Setup +## 📖 Provider Setup -### 🔐 Abonnementanbieter +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Profi-Tipp:** Verwenden Sie Opus für komplexe Aufgaben, Sonnet für Geschwindigkeit. OmniRoute verfolgt das Kontingent pro Modell! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (KOSTENLOS 180.000/Monat!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Bester Wert:** Riesiges kostenloses Kontingent! Verwenden Sie dies vor kostenpflichtigen Stufen. +**Best Value:** Huge free tier! Use this before paid tiers. -#### GitHub-Copilot +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Günstige Anbieter +### 💰 Cheap Providers -#### GLM-4.7 (Täglicher Reset, 0,6 $/1 Mio.) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Registrieren Sie sich: [Zhipu AI](https://open.bigmodel.cn/) -2. Holen Sie sich den API-Schlüssel vom Coding Plan -3. Dashboard → API-Schlüssel hinzufügen: Anbieter: `glm`, API-Schlüssel: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Verwendung:** `glm/glm-4.7` — **Profi-Tipp:** Coding Plan bietet 3× Kontingent zu 1/7 Kosten! Täglich um 10:00 Uhr zurückgesetzt. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 Stunden Zurücksetzen, 0,20 $/1 Mio.) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Registrieren Sie sich: [MiniMax](https://www.minimax.io/) -2. API-Schlüssel abrufen → Dashboard → API-Schlüssel hinzufügen +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Verwendung:** `minimax/MiniMax-M2.1` – **Profi-Tipp:** Günstigste Option für langen Kontext (1 Mio. Token)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (9 $/Monat pauschal) +#### Kimi K2 ($9/month flat) -1. Abonnieren: [Moonshot AI](https://platform.moonshot.ai/) -2. API-Schlüssel abrufen → Dashboard → API-Schlüssel hinzufügen +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Verwendung:** `kimi/kimi-latest` — **Profi-Tipp:** Feste 9 $/Monat für 10 Mio. Token = 0,90 $/1 Mio. effektive Kosten! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 KOSTENLOSE Anbieter +### 🆓 FREE Providers -#### iFlow (8 KOSTENLOSE Modelle) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 KOSTENLOSE Modelle) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude KOSTENLOS) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Kombinationen +## 🎨 Combos -### Beispiel 1: Abonnement maximieren → Günstiges Backup +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Beispiel 2: Nur kostenlos (kostenlos) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI-Integration +## 🔧 CLI Integration -### Cursor-IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -262,7 +262,7 @@ Settings → Models → Advanced: ### Claude Code -Bearbeiten Sie `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Bearbeiten Sie `~/.claude/config.json`: } ``` -### Codex-CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Bearbeiten Sie `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Bearbeiten Sie `~/.openclaw/openclaw.json`: } ``` -**Oder verwenden Sie Dashboard:** CLI-Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Weiter / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Bereitstellung +## 🚀 Deployment -### VPS-Bereitstellung +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Informationen zum hostintegrierten Modus mit CLI-Binärdateien finden Sie im Abschnitt „Docker“ in den Hauptdokumenten. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Umgebungsvariablen +### Environment Variables -| Variable | Standard | Beschreibung | -| --------------------- | ------------------------------------ | ------------------------------------------------------------------------ | ---- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT-Signaturgeheimnis (**Änderung in der Produktion**) | -| `INITIAL_PASSWORD` | `123456` | Erstes Login-Passwort | -| `DATA_DIR` | `~/.omniroute` | Datenverzeichnis (Datenbank, Nutzung, Protokolle) | -| `PORT` | Framework-Standard | Service-Port (`20128` in Beispielen) | -| `HOSTNAME` | Framework-Standard | Host binden (Docker ist standardmäßig `0.0.0.0`) | -| `NODE_ENV` | Laufzeitstandard | Legen Sie `production` für die Bereitstellung | fest | -| `BASE_URL` | `http://localhost:20128` | Serverseitige interne Basis-URL | -| `CLOUD_URL` | `https://omniroute.dev` | Basis-URL des Cloud-Synchronisierungsendpunkts | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC-Geheimnis für generierte API-Schlüssel | -| `REQUIRE_API_KEY` | `false` | Bearer-API-Schlüssel auf `/v1/*` erzwingen | -| `ENABLE_REQUEST_LOGS` | `false` | Aktiviert Anforderungs-/Antwortprotokolle | -| `AUTH_COOKIE_SECURE` | `false` | `Secure` Authentifizierungscookie erzwingen (hinter HTTPS-Reverse-Proxy) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Die vollständige Umgebungsvariablenreferenz finden Sie im [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Verfügbare Modelle +## 📊 Available Models
-Alle verfügbaren Modelle anzeigen +View all available models -**Claude Code (`cc/`)** – Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Codex (`cx/`)** – Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** – KOSTENLOS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** – 0,6 $/1 Mio.: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** – 0,2 $/1 Mio.: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** – KOSTENLOS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** – KOSTENLOS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** – KOSTENLOS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,15 +460,15 @@ Die vollständige Umgebungsvariablenreferenz finden Sie im [README](../README.md **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Perplexität (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` **Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Feuerwerks-KI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Großhirn (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Zusammenhang (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Die vollständige Umgebungsvariablenreferenz finden Sie im [README](../README.md --- -## 🧩 Erweiterte Funktionen +## 🧩 Advanced Features -### Benutzerdefinierte Modelle +### Custom Models -Fügen Sie jedem Anbieter eine beliebige Modell-ID hinzu, ohne auf ein App-Update warten zu müssen: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Oder verwenden Sie das Dashboard: **Anbieter → [Anbieter] → Benutzerdefinierte Modelle**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Dedizierte Anbieterrouten +### Dedicated Provider Routes -Leiten Sie Anfragen mit Modellvalidierung direkt an einen bestimmten Anbieter weiter: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Das Anbieterpräfix wird automatisch hinzugefügt, wenn es fehlt. Nicht übereinstimmende Modelle geben `400` zurück. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Netzwerk-Proxy-Konfiguration +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Vorrang:** Schlüsselspezifisch → Combo-spezifisch → Anbieterspezifisch → Global → Umgebung. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### Modellkatalog-API +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Gibt nach Anbieter gruppierte Modelle mit Typen (`chat`, `embedding`, `image`) zurück. +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Cloud-Synchronisierung +### Cloud Sync -- Synchronisieren Sie Anbieter, Kombinationen und Einstellungen geräteübergreifend -- Automatische Hintergrundsynchronisierung mit Timeout + Fail-Fast - – Bevorzugen Sie serverseitiges `BASE_URL`/`CLOUD_URL` in der Produktion +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production ### LLM Gateway Intelligence (Phase 9) -- **Semantischer Cache** – Nicht-Streaming-Antworten mit Temperatur = 0 werden automatisch zwischengespeichert (Umgehung mit `X-OmniRoute-No-Cache: true`) -- **Request Idempotency** – Dedupliziert Anfragen innerhalb von 5 Sekunden über den Header `Idempotency-Key` oder `X-Request-Id` -- **Fortschrittsverfolgung** – Opt-in-SSE-`event: progress`-Ereignisse über den `X-OmniRoute-Progress: true`-Header +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Übersetzerspielplatz +### Translator Playground -Zugriff über **Dashboard → Übersetzer**. Debuggen und visualisieren Sie, wie OmniRoute API-Anfragen zwischen Anbietern übersetzt. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Modus | Zweck | -| ---------------- | ------------------------------------------------------------------------------------------------------------------ | -| **Spielplatz** | Wählen Sie Quell-/Zielformate aus, fügen Sie eine Anfrage ein und sehen Sie sich sofort die übersetzte Ausgabe an | -| **Chat-Tester** | Senden Sie Live-Chat-Nachrichten über den Proxy und überprüfen Sie den gesamten Anfrage-/Antwortzyklus | -| **Prüfstand** | Führen Sie Batch-Tests über mehrere Formatkombinationen hinweg durch, um die Übersetzungskorrektheit zu überprüfen | -| **Live-Monitor** | Beobachten Sie Übersetzungen in Echtzeit, während Anfragen über den Proxy fließen | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Anwendungsfälle:** +**Use cases:** -- Debuggen Sie, warum eine bestimmte Client-/Provider-Kombination fehlschlägt -- Stellen Sie sicher, dass Denktags, Toolaufrufe und Systemaufforderungen korrekt übersetzt werden -- Vergleichen Sie Formatunterschiede zwischen den API-Formaten OpenAI, Claude, Gemini und Responses +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Routing-Strategien +### Routing Strategies -Konfigurieren Sie über **Dashboard → Einstellungen → Routing**. +Configure via **Dashboard → Settings → Routing**. -| Strategie | Beschreibung | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -| **Zuerst füllen** | Verwendet Konten in der Reihenfolge ihrer Priorität – das primäre Konto bearbeitet alle Anfragen, bis es nicht mehr verfügbar ist | -| **Round Robin** | Durchläuft alle Konten mit einem konfigurierbaren Sticky-Limit (Standard: 3 Anrufe pro Konto) | -| **P2C (Power of Two Choices)** | Wählt zwei zufällige Konten aus und leitet sie zum gesünderen weiter – gleicht Last mit Gesundheitsbewusstsein aus | -| **Zufällig** | Wählt für jede Anfrage per Fisher-Yates-Shuffle | zufällig ein Konto aus | -| **Am wenigsten genutzt** | Leitet zum Konto mit dem ältesten `lastUsedAt`-Zeitstempel weiter und verteilt den Datenverkehr gleichmäßig | -| **Kostenoptimiert** | Leitet zum Konto mit dem niedrigsten Prioritätswert weiter, optimiert für Anbieter mit den niedrigsten Kosten | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Wildcard-Modellaliase +#### Wildcard Model Aliases -Erstellen Sie Platzhaltermuster, um Modellnamen neu zuzuordnen: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Platzhalter unterstützen `*` (beliebige Zeichen) und `?` (einzelnes Zeichen). +Wildcards support `*` (any characters) and `?` (single character). -#### Fallback-Ketten +#### Fallback Chains -Definieren Sie globale Fallback-Ketten, die für alle Anfragen gelten: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Belastbarkeit und Leistungsschalter +### Resilience & Circuit Breakers -Konfigurieren Sie über **Dashboard → Einstellungen → Resilienz**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementiert Resilienz auf Anbieterebene mit vier Komponenten: +OmniRoute implements provider-level resilience with four components: -1. **Anbieterprofile** – Konfiguration pro Anbieter für: - - Fehlerschwelle (wie viele Fehler vor dem Öffnen) - - Abklingdauer - - Empfindlichkeit der Grenzfrequenzerkennung - - Exponentielle Backoff-Parameter +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Bearbeitbare Ratenbegrenzungen** – Standardeinstellungen auf Systemebene, konfigurierbar im Dashboard: - - **Anfragen pro Minute (RPM)** – Maximale Anfragen pro Minute und Konto - - **Min. Zeit zwischen Anfragen** – Mindestlücke in Millisekunden zwischen Anfragen - - **Max. gleichzeitige Anfragen** – Maximale gleichzeitige Anfragen pro Konto - - Klicken Sie zum Ändern auf **Bearbeiten** und dann auf **Speichern** oder **Abbrechen**. Werte bleiben über die Resilience-API bestehen. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Leistungsschalter** – Verfolgt Ausfälle pro Anbieter und öffnet automatisch den Stromkreis, wenn ein Schwellenwert erreicht wird: - - **GESCHLOSSEN** (fehlerfrei) – Anfragen fließen normal - - **OFFEN** – Der Anbieter ist nach wiederholten Ausfällen vorübergehend gesperrt - - **HALF_OPEN** – Testen, ob sich der Anbieter erholt hat +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Richtlinien und Sperrkennungen** – Zeigt den Status des Leistungsschalters und die Sperrkennungen mit der Möglichkeit zum erzwungenen Entsperren an. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Automatische Erkennung von Ratenbegrenzungen** – Überwacht die Header `429` und `Retry-After`, um proaktiv zu vermeiden, dass die Ratenbegrenzungen der Anbieter erreicht werden. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Profi-Tipp:** Verwenden Sie die Schaltfläche **Alle zurücksetzen**, um alle Leistungsschalter und Abklingzeiten zu löschen, wenn ein Anbieter nach einem Ausfall wiederhergestellt wird. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Datenbankexport/-import +### Database Export / Import -Verwalten Sie Datenbanksicherungen unter **Dashboard → Einstellungen → System & Speicher**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Aktion | Beschreibung | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Datenbank exportieren** | Lädt die aktuelle SQLite-Datenbank als `.sqlite`-Datei herunter | -| **Alle exportieren (.tar.gz)** | Lädt ein vollständiges Backup-Archiv herunter, einschließlich: Datenbank, Einstellungen, Kombinationen, Anbieterverbindungen (keine Anmeldeinformationen), API-Schlüsselmetadaten | -| **Datenbank importieren** | Laden Sie eine `.sqlite`-Datei hoch, um die aktuelle Datenbank zu ersetzen. Es wird automatisch ein Backup vor dem Import erstellt | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Importvalidierung:** Die importierte Datei wird auf Integrität (SQLite-Pragmaprüfung), erforderliche Tabellen (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) und Größe (max. 100 MB) validiert. +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Anwendungsfälle:** +**Use Cases:** -- OmniRoute zwischen Maschinen migrieren -- Erstellen Sie externe Backups für die Notfallwiederherstellung -- Konfigurationen zwischen Teammitgliedern teilen (alle exportieren → Archiv teilen) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Einstellungs-Dashboard +### Settings Dashboard -Die Einstellungsseite ist zur einfachen Navigation in 5 Registerkarten unterteilt: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Inhalt | -| ------------------- | ----------------------------------------------------------------------------------------------------------------- | -| **Sicherheit** | Anmelde-/Passworteinstellungen, IP-Zugriffskontrolle, API-Authentifizierung für `/models` und Anbieterblockierung | -| **Routing** | Globale Routing-Strategie (6 Optionen), Wildcard-Modell-Aliase, Fallback-Ketten, Combo-Standardwerte | -| **Belastbarkeit** | Anbieterprofile, bearbeitbare Tarifbegrenzungen, Leistungsschalterstatus, Richtlinien und Sperrkennungen | -| **KI** | Denken Sie an die Budgetkonfiguration, die globale System-Prompt-Injektion, die Prompt-Cache-Statistiken | -| **Fortgeschritten** | Globale Proxy-Konfiguration (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Kosten- und Budgetmanagement +### Costs & Budget Management -Zugang über **Dashboard → Kosten**. +Access via **Dashboard → Costs**. -| Tab | Zweck | -| ---------- | ------------------------------------------------------------------------------------------------------- | -| **Budget** | Legen Sie Ausgabenlimits pro API-Schlüssel mit Tages-/Wochen-/Monatsbudgets und Echtzeitverfolgung fest | -| **Preise** | Modellpreiseinträge anzeigen und bearbeiten – Kosten pro 1.000 Ein-/Ausgabe-Tokens pro Anbieter | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Kostenverfolgung:** Bei jeder Anfrage wird die Token-Nutzung protokolliert und die Kosten anhand der Preistabelle berechnet. Sehen Sie sich Aufschlüsselungen in **Dashboard → Nutzung** nach Anbieter, Modell und API-Schlüssel an. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Audiotranskription +### Audio Transcription -OmniRoute unterstützt die Audiotranskription über den OpenAI-kompatiblen Endpunkt: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Verfügbare Anbieter: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Unterstützte Audioformate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Combo-Balancing-Strategien +### Combo Balancing Strategies -Konfigurieren Sie die Balance pro Combo unter **Dashboard → Combos → Erstellen/Bearbeiten → Strategie**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategie | Beschreibung | -| ------------------------ | ---------------------------------------------------------------------------------------------- | -| **Round-Robin** | Rotiert nacheinander durch die Modelle | -| **Priorität** | Versucht immer das erste Modell; fällt nur bei Fehler zurück | -| **Zufällig** | Wählt für jede Anfrage ein zufälliges Modell aus der Kombination aus | -| **Gewichtet** | Routen proportional basierend auf den zugewiesenen Gewichten pro Modell | -| **Am wenigsten genutzt** | Leitet zum Modell mit den wenigsten aktuellen Anfragen weiter (verwendet Kombinationsmetriken) | -| **Kostenoptimiert** | Leitet zum günstigsten verfügbaren Modell (unter Verwendung der Preistabelle) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Globale Combo-Standards können unter **Dashboard → Einstellungen → Routing → Combo-Standards** festgelegt werden. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Gesundheits-Dashboard +### Health Dashboard -Zugriff über **Dashboard → Gesundheit**. Echtzeit-Übersicht über den Systemzustand mit 6 Karten: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Karte | Was es zeigt | -| ---------------------- | ------------------------------------------------------------------------- | -| **Systemstatus** | Betriebszeit, Version, Speichernutzung, Datenverzeichnis | -| **Anbietergesundheit** | Zustand des Leistungsschalters pro Anbieter (geschlossen/offen/halboffen) | -| **Ratenlimits** | Aktive Abklingzeiten pro Konto mit verbleibender Zeit | -| **Aktive Sperren** | Anbieter, die durch die Sperrrichtlinie vorübergehend gesperrt sind | -| **Signatur-Cache** | Statistiken zum Deduplizierungs-Cache (aktive Schlüssel, Trefferquote) | -| **Latenztelemetrie** | p50/p95/p99-Latenzaggregation pro Anbieter | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Profi-Tipp:** Die Gesundheitsseite wird alle 10 Sekunden automatisch aktualisiert. Verwenden Sie die Leistungsschalterkarte, um zu ermitteln, bei welchen Anbietern Probleme auftreten. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/es/API_REFERENCE.md b/docs/i18n/es/API_REFERENCE.md index 55ab1185b9..b795722c11 100644 --- a/docs/i18n/es/API_REFERENCE.md +++ b/docs/i18n/es/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Referencia de API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Referencia completa para todos los puntos finales de la API de OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Tabla de contenidos +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Referencia completa para todos los puntos finales de la API de OmniRoute. --- -## Finalizaciones de chat +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Encabezados personalizados +### Custom Headers -| Encabezado | Dirección | Descripción | -| ------------------------ | --------- | ------------------------------------------------------ | -| `X-OmniRoute-No-Cache` | Solicitar | Establezca en `true` para omitir el caché | -| `X-OmniRoute-Progress` | Solicitar | Establecer en `true` para eventos de progreso | -| `Idempotency-Key` | Solicitar | Clave de desduplicación (ventana 5s) | -| `X-Request-Id` | Solicitar | Clave de desduplicación alternativa | -| `X-OmniRoute-Cache` | Respuesta | `HIT` o `MISS` (sin transmisión) | -| `X-OmniRoute-Idempotent` | Respuesta | `true` si está deduplicado | -| `X-OmniRoute-Progress` | Respuesta | `enabled` si el seguimiento del progreso está activado | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Incrustaciones +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Proveedores disponibles: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Generación de imágenes +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Proveedores disponibles: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Listar modelos +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Puntos finales de compatibilidad +## Compatibility Endpoints -| Método | Camino | Formato | -| -------- | --------------------------- | ------------------------ | -| PUBLICAR | `/v1/chat/completions` | Abierta AI | -| PUBLICAR | `/v1/messages` | Antrópico | -| PUBLICAR | `/v1/responses` | Respuestas de OpenAI | -| PUBLICAR | `/v1/embeddings` | Abierta AI | -| PUBLICAR | `/v1/images/generations` | Abierta AI | -| OBTENER | `/v1/models` | Abierta AI | -| PUBLICAR | `/v1/messages/count_tokens` | Antrópico | -| OBTENER | `/v1beta/models` | Géminis | -| PUBLICAR | `/v1beta/models/{...path}` | Géminis genera contenido | -| PUBLICAR | `/v1/api/chat` | Ollamá | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Rutas de proveedores dedicadas +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -El prefijo del proveedor se agrega automáticamente si falta. Los modelos no coincidentes devuelven `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Caché semántico +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Ejemplo de respuesta: +Response example: ```json { @@ -162,154 +162,164 @@ Ejemplo de respuesta: --- -## Panel de control y gestión +## Dashboard & Management -### Autenticación +### Authentication -| Punto final | Método | Descripción | -| ----------------------------- | ------------- | ----------------------------------- | -| `/api/auth/login` | PUBLICAR | Iniciar sesión | -| `/api/auth/logout` | PUBLICAR | Cerrar sesión | -| `/api/settings/require-login` | OBTENER/PONER | Alternar inicio de sesión requerido | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Gestión de proveedores +### Provider Management -| Punto final | Método | Descripción | -| ---------------------------- | ------------------------- | ----------------------------------- | -| `/api/providers` | OBTENER/PUBLICAR | Listar/crear proveedores | -| `/api/providers/[id]` | OBTENER/PONER/ELIMINAR | Gestionar un proveedor | -| `/api/providers/[id]/test` | PUBLICAR | Conexión del proveedor de pruebas | -| `/api/providers/[id]/models` | OBTENER | Listar modelos de proveedores | -| `/api/providers/validate` | PUBLICAR | Validar configuración del proveedor | -| `/api/provider-nodes*` | Varios | Gestión de nodos de proveedores | -| `/api/provider-models` | OBTENER/PUBLICAR/ELIMINAR | Modelos personalizados | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Flujos de OAuth +### OAuth Flows -| Punto final | Método | Descripción | -| -------------------------------- | ------ | ------------------------------ | -| `/api/oauth/[provider]/[action]` | Varios | OAuth específico del proveedor | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Enrutamiento y configuración +### Routing & Config -| Punto final | Método | Descripción | -| --------------------- | ---------------- | -------------------------------------- | -| `/api/models/alias` | OBTENER/PUBLICAR | Alias ​​de modelos | -| `/api/models/catalog` | OBTENER | Todos los modelos por proveedor + tipo | -| `/api/combos*` | Varios | Gestión combinada | -| `/api/keys*` | Varios | Gestión de claves API | -| `/api/pricing` | OBTENER | Precios del modelo | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Uso y análisis +### Usage & Analytics -| Punto final | Método | Descripción | -| --------------------------- | ------- | ------------------------------ | -| `/api/usage/history` | OBTENER | Historial de uso | -| `/api/usage/logs` | OBTENER | Registros de uso | -| `/api/usage/request-logs` | OBTENER | Registros a nivel de solicitud | -| `/api/usage/[connectionId]` | OBTENER | Uso por conexión | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Configuración +### Settings -| Punto final | Método | Descripción | -| ------------------------------- | ------------- | --------------------------------------- | -| `/api/settings` | OBTENER/PONER | Configuraciones generales | -| `/api/settings/proxy` | OBTENER/PONER | Configuración de proxy de red | -| `/api/settings/proxy/test` | PUBLICAR | Probar conexión proxy | -| `/api/settings/ip-filter` | OBTENER/PONER | Lista de IP permitidas/lista de bloqueo | -| `/api/settings/thinking-budget` | OBTENER/PONER | Presupuesto simbólico de razonamiento | -| `/api/settings/system-prompt` | OBTENER/PONER | Aviso del sistema global | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Monitoreo +### Monitoring -| Punto final | Método | Descripción | -| ------------------------ | ---------------- | ------------------------------ | -| `/api/sessions` | OBTENER | Seguimiento de sesión activa | -| `/api/rate-limits` | OBTENER | Límites de tasas por cuenta | -| `/api/monitoring/health` | OBTENER | Control de salud | -| `/api/cache` | OBTENER/ELIMINAR | Estadísticas de caché / borrar | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Copia de seguridad y exportación/importación +### Backup & Export/Import -| Punto final | Método | Descripción | -| --------------------------- | -------- | ------------------------------------------------------------- | -| `/api/db-backups` | OBTENER | Listar copias de seguridad disponibles | -| `/api/db-backups` | PONER | Crear una copia de seguridad manual | -| `/api/db-backups` | PUBLICAR | Restaurar desde una copia de seguridad específica | -| `/api/db-backups/export` | OBTENER | Descargar la base de datos como archivo .sqlite | -| `/api/db-backups/import` | PUBLICAR | Cargue el archivo .sqlite para reemplazar la base de datos | -| `/api/db-backups/exportAll` | OBTENER | Descargue la copia de seguridad completa como archivo .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Sincronización en la nube +### Cloud Sync -| Punto final | Método | Descripción | -| ---------------------- | -------- | ---------------------------------------- | -| `/api/sync/cloud` | Varios | Operaciones de sincronización en la nube | -| `/api/sync/initialize` | PUBLICAR | Inicializar sincronización | -| `/api/cloud/*` | Varios | Gestión de la nube | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Herramientas CLI +### CLI Tools -| Punto final | Método | Descripción | -| ---------------------------------- | ------- | ----------------------------------- | -| `/api/cli-tools/claude-settings` | OBTENER | Estado de Claude CLI | -| `/api/cli-tools/codex-settings` | OBTENER | Estado de la CLI del Códice | -| `/api/cli-tools/droid-settings` | OBTENER | Estado de la CLI del droide | -| `/api/cli-tools/openclaw-settings` | OBTENER | Estado de la CLI de OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | OBTENER | Tiempo de ejecución de CLI genérico | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Las respuestas de CLI incluyen: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Resiliencia y límites de tasas +### ACP Agents -| Punto final | Método | Descripción | -| ----------------------- | ------------- | ------------------------------------------ | -| `/api/resilience` | OBTENER/PONER | Obtener/actualizar perfiles de resiliencia | -| `/api/resilience/reset` | PUBLICAR | Restablecer disyuntores | -| `/api/rate-limits` | OBTENER | Estado del límite de tasa por cuenta | -| `/api/rate-limit` | OBTENER | Configuración del límite de tasa global | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Evaluaciones +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Punto final | Método | Descripción | -| ------------ | ---------------- | -------------------------------------------------- | -| `/api/evals` | OBTENER/PUBLICAR | Listar conjuntos de evaluación/ejecutar evaluación | +### Resilience & Rate Limits -### Políticas +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Punto final | Método | Descripción | -| --------------- | ------------------------- | ------------------------------------- | -| `/api/policies` | OBTENER/PUBLICAR/ELIMINAR | Administrar políticas de enrutamiento | +### Evals -### Cumplimiento +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Punto final | Método | Descripción | -| --------------------------- | ------- | ------------------------------------------------ | -| `/api/compliance/audit-log` | OBTENER | Registro de auditoría de cumplimiento (última N) | +### Policies -### v1beta (Compatible con Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Punto final | Método | Descripción | -| -------------------------- | -------- | ------------------------------------- | -| `/v1beta/models` | OBTENER | Listar modelos en formato Gemini | -| `/v1beta/models/{...path}` | PUBLICAR | Géminis `generateContent` punto final | +### Compliance -Estos puntos finales reflejan el formato API de Gemini para clientes que esperan compatibilidad nativa con el SDK de Gemini. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### API internas/del sistema +### v1beta (Gemini-Compatible) -| Punto final | Método | Descripción | -| --------------- | -------- | ----------------------------------------------------------------------------------- | -| `/api/init` | OBTENER | Comprobación de inicialización de la aplicación (utilizada en la primera ejecución) | -| `/api/tags` | OBTENER | Etiquetas de modelo compatibles con Ollama (para clientes de Ollama) | -| `/api/restart` | PUBLICAR | Activar reinicio ordenado del servidor | -| `/api/shutdown` | PUBLICAR | Activar el cierre ordenado del servidor | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Nota:** Estos puntos finales se utilizan internamente por el sistema o para la compatibilidad del cliente Ollama. Por lo general, los usuarios finales no los llaman. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Transcripción de audio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transcribe archivos de audio usando Deepgram o AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Solicitud:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Respuesta:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Proveedores admitidos:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Formatos admitidos:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Compatibilidad con Ollama +## Ollama Compatibility -Para clientes que utilizan el formato API de Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Las solicitudes se traducen automáticamente entre Ollama y los formatos internos. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetría +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Respuesta:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Presupuesto +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Disponibilidad del modelo +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Procesamiento de solicitudes +## Request Processing -1. El cliente envía la solicitud a `/v1/*` -2. Llamadas del controlador de ruta `handleChat`, `handleEmbedding`, `handleAudioTranscription` o `handleImageGeneration` -3. Se resuelve el modelo (proveedor directo/modelo o alias/combo) -4. Credenciales seleccionadas de la base de datos local con filtrado de disponibilidad de cuenta -5. Para chat: `handleChatCore`: detección de formato, traducción, verificación de caché, verificación de idempotencia -6. El ejecutor del proveedor envía una solicitud ascendente -7. Respuesta traducida al formato del cliente (chat) o devuelta tal como está (incrustaciones/imágenes/audio) -8. Uso/registro registrado -9. El respaldo se aplica en caso de errores de acuerdo con las reglas combinadas. +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Referencia de arquitectura completa: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Autenticación +## Authentication -- Las rutas del panel (`/dashboard/*`) utilizan la cookie `auth_token` -- El inicio de sesión utiliza el hash de contraseña guardado; recurrir a `INITIAL_PASSWORD` -- `requireLogin` conmutable a través de `/api/settings/require-login` -- Las rutas `/v1/*` opcionalmente requieren una clave API de portador cuando `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/es/ARCHITECTURE.md b/docs/i18n/es/ARCHITECTURE.md index 9d78cbf707..258d62df53 100644 --- a/docs/i18n/es/ARCHITECTURE.md +++ b/docs/i18n/es/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Arquitectura OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Última actualización: 2026-02-18_ +_Last updated: 2026-03-04_ -## Resumen ejecutivo +## Executive Summary -OmniRoute es un panel y una puerta de enlace de enrutamiento de IA local creado en Next.js. -Proporciona un único punto final compatible con OpenAI (`/v1/*`) y enruta el tráfico a través de múltiples proveedores ascendentes con traducción, respaldo, actualización de tokens y seguimiento de uso. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Capacidades principales: +Core capabilities: -- Superficie API compatible con OpenAI para CLI/herramientas (28 proveedores) -- Traducción de solicitudes/respuestas entre formatos de proveedores. -- Modelo combinado de respaldo (secuencia multimodelo) -- Respaldo a nivel de cuenta (varias cuentas por proveedor) -- Gestión de conexión de proveedor de claves OAuth + API -- Generación de incrustación vía `/v1/embeddings` (6 proveedores, 9 modelos) -- Generación de imágenes vía `/v1/images/generations` (4 proveedores, 9 modelos) -- Piense en el análisis de etiquetas (`...`) para modelos de razonamiento -- Saneamiento de respuesta para una estricta compatibilidad con OpenAI SDK -- Normalización de roles (desarrollador → sistema, sistema → usuario) para compatibilidad entre proveedores -- Conversión de salida estructurada (json_schema → Gemini ResponseSchema) -- Persistencia local para proveedores, claves, alias, combos, configuraciones, precios. -- Seguimiento de uso/costos y registro de solicitudes -- Sincronización en la nube opcional para sincronización multidispositivo/estado -- Lista de IP permitidas/lista de bloqueo para control de acceso a API -- Pensando en la gestión del presupuesto (transferencia/automática/personalizada/adaptativa) -- Inyección rápida del sistema global -- Seguimiento de sesiones y toma de huellas digitales -- Limitación de tarifas mejorada por cuenta con perfiles específicos del proveedor -- Patrón de disyuntor para la resiliencia del proveedor -- Protección de rebaño anti-truenos con bloqueo mutex -- Caché de deduplicación de solicitudes basado en firmas -- Capa de dominio: disponibilidad del modelo, reglas de costos, política de respaldo, política de bloqueo -- Persistencia del estado del dominio (caché de escritura SQLite para respaldos, presupuestos, bloqueos, disyuntores) -- Motor de políticas para la evaluación centralizada de solicitudes (bloqueo → presupuesto → respaldo) -- Solicitar telemetría con agregación de latencia p50/p95/p99 -- ID de correlación (X-Request-Id) para seguimiento de un extremo a otro -- Registro de auditoría de cumplimiento con opción de exclusión por clave API -- Marco de evaluación para el aseguramiento de la calidad del LLM. -- Panel de interfaz de usuario de resiliencia con estado del disyuntor en tiempo real -- Proveedores modulares de OAuth (12 módulos individuales bajo `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Modelo de tiempo de ejecución principal: +Primary runtime model: -- Las rutas de la aplicación Next.js bajo `src/app/api/*` implementan API de panel y API de compatibilidad. -- Un núcleo de enrutamiento/SSE compartido en `src/sse/*` + `open-sse/*` maneja la ejecución, traducción, transmisión, respaldo y uso del proveedor. +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Alcance y límites +## Scope and Boundaries -### En alcance +### In Scope -- Tiempo de ejecución de la puerta de enlace local -- API de gestión de paneles -- Autenticación de proveedor y actualización de token -- Solicitar traducción y transmisión SSE -- Estado local + persistencia de uso. -- Orquestación de sincronización en la nube opcional +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Fuera de alcance +### Out of Scope -- Implementación del servicio en la nube detrás de `NEXT_PUBLIC_CLOUD_URL` -- Proveedor SLA/plano de control fuera del proceso local -- Los propios binarios CLI externos (Claude CLI, Codex CLI, etc.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Contexto del sistema de alto nivel +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Componentes principales del tiempo de ejecución +## Core Runtime Components -## 1) API y capa de enrutamiento (rutas de la aplicación Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Directorios principales: +Main directories: -- `src/app/api/v1/*` y `src/app/api/v1beta/*` para API de compatibilidad -- `src/app/api/*` para API de administración/configuración -- Siguientes reescrituras en `next.config.mjs` asignan `/v1/*` a `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Rutas de compatibilidad importantes: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — incluye modelos personalizados con `custom: true` -- `src/app/api/v1/embeddings/route.ts` — generación de incrustación (6 proveedores) -- `src/app/api/v1/images/generations/route.ts` — generación de imágenes (4+ proveedores, incluido Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — chat dedicado por proveedor -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — incorporaciones dedicadas por proveedor -- `src/app/api/v1/providers/[provider]/images/generations/route.ts`: imágenes dedicadas por proveedor +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Dominios de gestión: +Management domains: -- Autenticación/configuración: `src/app/api/auth/*`, `src/app/api/settings/*` -- Proveedores/conexiones: `src/app/api/providers*` -- Nodos proveedores: `src/app/api/provider-nodes*` -- Modelos personalizados: `src/app/api/provider-models` (GET/POST/DELETE) -- Catálogo de modelos: `src/app/api/models/catalog` (OBTENER) -- Configuración de proxy: `src/app/api/settings/proxy` (OBTENER/PONER/BORRAR) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Claves/alias/combos/precios: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Uso: `src/app/api/usage/*` -- Sincronización/nube: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Ayudantes de herramientas CLI: `src/app/api/cli-tools/*` -- Filtro IP: `src/app/api/settings/ip-filter` (OBTENER/PUT) -- Presupuesto de pensamiento: `src/app/api/settings/thinking-budget` (GET/PUT) -- Mensaje del sistema: `src/app/api/settings/system-prompt` (OBTENER/PUT) -- Sesiones: `src/app/api/sessions` (OBTENER) -- Límites de tasa: `src/app/api/rate-limits` (GET) -- Resiliencia: `src/app/api/resilience` (GET/PATCH): perfiles de proveedor, disyuntor, estado límite de velocidad -- Restablecimiento de resiliencia: `src/app/api/resilience/reset` (POST) — restablecer interruptores + tiempos de reutilización -- Estadísticas de caché: `src/app/api/cache/stats` (OBTENER/ELIMINAR) -- Disponibilidad del modelo: `src/app/api/models/availability` (GET/POST) -- Telemetría: `src/app/api/telemetry/summary` (OBTENER) -- Presupuesto: `src/app/api/usage/budget` (GET/POST) -- Cadenas de respaldo: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Auditoría de cumplimiento: `src/app/api/compliance/audit-log` (GET) -- Evaluaciones: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Políticas: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Núcleo de traducción +## 2) SSE + Translation Core -Módulos de flujo principales: +Main flow modules: -- Entrada: `src/sse/handlers/chat.ts` -- Orquestación central: `open-sse/handlers/chatCore.ts` -- Adaptadores de ejecución del proveedor: `open-sse/executors/*` -- Detección de formato/configuración del proveedor: `open-sse/services/provider.ts` -- Análisis/resolución del modelo: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Lógica de reserva de cuenta: `open-sse/services/accountFallback.ts` -- Registro de traducción: `open-sse/translator/index.ts` -- Transformaciones de flujo: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Extracción/normalización de uso: `open-sse/utils/usageTracking.ts` -- Piense en el analizador de etiquetas: `open-sse/utils/thinkTagParser.ts` -- Controlador de incrustación: `open-sse/handlers/embeddings.ts` -- Incrustar registro de proveedores: `open-sse/config/embeddingRegistry.ts` -- Controlador de generación de imágenes: `open-sse/handlers/imageGeneration.ts` -- Registro de proveedor de imágenes: `open-sse/config/imageRegistry.ts` -- Sanitización de respuesta: `open-sse/handlers/responseSanitizer.ts` -- Normalización de roles: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Servicios (lógica de negocios): +Services (business logic): -- Selección/puntuación de cuenta: `open-sse/services/accountSelector.ts` -- Gestión del ciclo de vida del contexto: `open-sse/services/contextManager.ts` -- Aplicación del filtro IP: `open-sse/services/ipFilter.ts` -- Seguimiento de sesión: `open-sse/services/sessionManager.ts` -- Solicitar deduplicación: `open-sse/services/signatureCache.ts` -- Inyección de aviso del sistema: `open-sse/services/systemPrompt.ts` -- Pensando en la gestión del presupuesto: `open-sse/services/thinkingBudget.ts` -- Enrutamiento del modelo comodín: `open-sse/services/wildcardRouter.ts` -- Gestión de límites de tarifas: `open-sse/services/rateLimitManager.ts` -- Disyuntor: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Módulos de capa de dominio: +Domain layer modules: -- Disponibilidad del modelo: `src/lib/domain/modelAvailability.ts` -- Reglas de costos/presupuestos: `src/lib/domain/costRules.ts` -- Política alternativa: `src/lib/domain/fallbackPolicy.ts` -- Resolución combinada: `src/lib/domain/comboResolver.ts` -- Política de bloqueo: `src/lib/domain/lockoutPolicy.ts` -- Motor de políticas: `src/domain/policyEngine.ts` — bloqueo centralizado → presupuesto → evaluación alternativa -- Catálogo de códigos de error: `src/lib/domain/errorCodes.ts` -- ID de solicitud: `src/lib/domain/requestId.ts` -- Tiempo de espera de recuperación: `src/lib/domain/fetchTimeout.ts` -- Solicitar telemetría: `src/lib/domain/requestTelemetry.ts` -- Cumplimiento/auditoría: `src/lib/domain/compliance/index.ts` -- Corredor de evaluación: `src/lib/domain/evalRunner.ts` -- Persistencia del estado del dominio: `src/lib/db/domainState.ts` — SQLite CRUD para cadenas de respaldo, presupuestos, historial de costos, estado de bloqueo, disyuntores +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Módulos del proveedor OAuth (12 archivos individuales bajo `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Índice de registro: `src/lib/oauth/providers/index.ts` -- Proveedores individuales: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Contenedor delgado: `src/lib/oauth/providers.ts` — reexportaciones desde módulos individuales +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Capa de persistencia +## 3) Persistence Layer -BD de estado primario: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- archivo: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` cuando está configurado, en caso contrario `~/.omniroute/db.json`) -- entidades: proveedoresConexiones, proveedoresNodos, modelAliases, combos, apiKeys, configuraciones, precios, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Base de datos de uso: +Usage persistence: -- `src/lib/usageDb.ts` -- archivos: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- sigue la misma política de directorio base que `localDb` (`DATA_DIR`, luego `XDG_CONFIG_HOME/omniroute` cuando se establece) -- descompuesto en submódulos enfocados: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -Base de datos de estado de dominio (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — Operaciones CRUD para el estado del dominio -- Tablas (creadas en `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Patrón de caché de escritura simultánea: los mapas en memoria tienen autoridad en tiempo de ejecución; las mutaciones se escriben sincrónicamente en SQLite; El estado se restaura desde la base de datos en el arranque en frío. +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Autenticación + Superficies de seguridad +## 4) Auth + Security Surfaces -- Autenticación de cookies del panel: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Generación/verificación de clave API: `src/shared/utils/apiKey.ts` -- Los secretos del proveedor persistieron en `providerConnections` entradas -- Soporte de proxy saliente a través de `open-sse/utils/proxyFetch.ts` (env vars) y `open-sse/utils/networkProxy.ts` (configurable por proveedor o global) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Sincronización en la nube +## 5) Cloud Sync -- Inicio del programador: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Tarea periódica: `src/shared/services/cloudSyncScheduler.ts` -- Ruta de control: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Solicitar ciclo de vida (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Flujo alternativo de cuenta +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Las decisiones alternativas están impulsadas por `open-sse/services/accountFallback.ts` utilizando códigos de estado y heurísticas de mensajes de error. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Incorporación de OAuth y ciclo de vida de actualización de tokens +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -La actualización durante el tráfico en vivo se ejecuta dentro de `open-sse/handlers/chatCore.ts` a través del ejecutor `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Ciclo de vida de sincronización en la nube (activar/sincronizar/desactivar) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -La sincronización periódica la activa `CloudSyncScheduler` cuando la nube está habilitada. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Modelo de datos y mapa de almacenamiento +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Archivos de almacenamiento físico: +Physical storage files: -- estado principal: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` cuando está configurado, en caso contrario `~/.omniroute/db.json`) -- estadísticas de uso: `${DATA_DIR}/usage.json` -- líneas de registro de solicitud: `${DATA_DIR}/log.txt` -- traductor opcional/solicitar sesiones de depuración: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topología de implementación +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Mapeo de módulos (de decisión crítica) +## Module Mapping (Decision-Critical) -### Módulos de ruta y API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API de compatibilidad -- `src/app/api/v1/providers/[provider]/*`: rutas dedicadas por proveedor (chat, incrustaciones, imágenes) -- `src/app/api/providers*`: proveedor CRUD, validación, pruebas -- `src/app/api/provider-nodes*`: gestión de nodos compatibles personalizados -- `src/app/api/provider-models`: gestión de modelos personalizados (CRUD) -- `src/app/api/models/catalog`: API de catálogo de modelos completo (todos los tipos agrupados por proveedor) -- `src/app/api/oauth/*`: flujos de código de dispositivo/OAuth -- `src/app/api/keys*`: ciclo de vida de la clave API local -- `src/app/api/models/alias`: gestión de alias -- `src/app/api/combos*`: gestión de combos alternativos -- `src/app/api/pricing`: anulaciones de precios para el cálculo de costos -- `src/app/api/settings/proxy`: configuración de proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: prueba de conectividad de proxy saliente (POST) -- `src/app/api/usage/*`: API de uso y registros -- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronización en la nube y ayudantes orientados a la nube -- `src/app/api/cli-tools/*`: escritores/comprobadores de configuración CLI local -- `src/app/api/settings/ip-filter`: lista de IP permitidas/lista de bloqueo (GET/PUT) -- `src/app/api/settings/thinking-budget`: configuración del presupuesto del token pensante (GET/PUT) -- `src/app/api/settings/system-prompt`: mensaje global del sistema (GET/PUT) -- `src/app/api/sessions`: listado de sesiones activas (GET) -- `src/app/api/rate-limits`: estado de límite de tasa por cuenta (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Núcleo de enrutamiento y ejecución +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: análisis de solicitudes, manejo de combos, bucle de selección de cuentas -- `open-sse/handlers/chatCore.ts`: traducción, envío de ejecutores, manejo de reintento/actualización, configuración de transmisión -- `open-sse/executors/*`: comportamiento de formato y red específico del proveedor +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Registro de traducción y convertidores de formato +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: registro y orquestación de traductores -- Solicitar traductores: `open-sse/translator/request/*` -- Traductores de respuesta: `open-sse/translator/response/*` -- Constantes de formato: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Persistencia +### Persistence -- `src/lib/localDb.ts`: configuración/estado persistente -- `src/lib/usageDb.ts`: historial de uso y registros continuos de solicitudes +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Cobertura del Ejecutor del Proveedor (Patrón de Estrategia) +## Provider Executor Coverage (Strategy Pattern) -Cada proveedor tiene un ejecutor especializado que extiende `BaseExecutor` (en `open-sse/executors/base.ts`), que proporciona creación de URL, construcción de encabezados, reintentos con retroceso exponencial, enlaces de actualización de credenciales y el método de orquestación `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Ejecutor | Proveedor(es) | Manejo Especial | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configuración dinámica de URL/encabezado por proveedor | -| `AntigravityExecutor` | Antigravedad de Google | ID personalizados de proyecto/sesión, reintento después del análisis | -| `CodexExecutor` | Códice OpenAI | Inyecta instrucciones del sistema, fuerza el esfuerzo de razonamiento | -| `CursorExecutor` | Cursor IDE | Protocolo ConnectRPC, codificación Protobuf, solicitud de firma mediante suma de comprobación | -| `GithubExecutor` | Copiloto de GitHub | Actualización del token Copilot, encabezados que imitan VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binario de AWS EventStream → Conversión SSE | -| `GeminiCLIExecutor` | Géminis CLI | Ciclo de actualización del token OAuth de Google | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Todos los demás proveedores (incluidos los nodos compatibles personalizados) utilizan `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matriz de compatibilidad de proveedores +## Provider Compatibility Matrix -| Proveedor | Formato | Autenticación | Corriente | Sin transmisión | Actualización de token | API de uso | -| ---------------------- | ----------------- | ---------------------------------- | --------------------------- | --------------- | ---------------------- | ------------------------- | -| Claudio | claudio | Clave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Solo administrador | -| Géminis | géminis | Clave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Consola en la nube | -| Géminis CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Consola en la nube | -| Antigravedad | antigravedad | OAuth | ✅ | ✅ | ✅ | ✅ API de cuota completa | -| Abierta AI | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| Códice | respuestas-openai | OAuth | ✅ forzado | ❌ | ✅ | ✅ Límites de tarifas | -| Copiloto de GitHub | abierto | OAuth + Token de copiloto | ✅ | ✅ | ✅ | ✅ Instantáneas de cuotas | -| Cursores | cursor | Suma de comprobación personalizada | ✅ | ✅ | ❌ | ❌ | -| kiro | kiro | AWS SSO OIDC | ✅ (Transmisión de eventos) | ❌ | ✅ | ✅ Límites de uso | -| Qwen | abierto | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitud | -| iFlujo | abierto | OAuth (básico) | ✅ | ✅ | ✅ | ⚠️ Por solicitud | -| Enrutador abierto | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claudio | Clave API | ✅ | ✅ | ❌ | ❌ | -| Búsqueda profunda | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| Groq | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| Mistral | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| Perplejidad | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| Juntos IA | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| Fuegos artificiales AI | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| Cerebras | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| Coherir | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | -| NIM de NVIDIA | abierto | Clave API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Cobertura de traducción de formato +## Format Translation Coverage -Los formatos de origen detectados incluyen: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Los formatos de destino incluyen: +Target formats include: -- Chat/Respuestas de OpenAI -- Claudio -- Géminis/Gemini-CLI/sobre antigravedad - -Kiro -- Cursores +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -Las traducciones utilizan **OpenAI como formato central**; todas las conversiones pasan por OpenAI como formato intermedio: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Las traducciones se seleccionan dinámicamente según la forma de la carga útil de origen y el formato de destino del proveedor. +Translations are selected dynamically based on source payload shape and provider target format. -Capas de procesamiento adicionales en el proceso de traducción: +Additional processing layers in the translation pipeline: -- **Desinfección de respuestas**: elimina los campos no estándar de las respuestas en formato OpenAI (tanto en streaming como sin streaming) para garantizar el estricto cumplimiento del SDK. -- **Normalización de roles**: convierte `developer` → `system` para objetivos que no son OpenAI; fusiona `system` → `user` para modelos que rechazan el rol del sistema (GLM, ERNIE) -- **Piense en la extracción de etiquetas**: analiza `...` bloques del contenido en el campo `reasoning_content` -- **Salida estructurada**: convierte OpenAI `response_format.json_schema` en `responseMimeType` + `responseSchema` de Gemini. +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Puntos finales API compatibles +## Supported API Endpoints -| Punto final | Formato | Manejador | -| -------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------- | -| `POST /v1/chat/completions` | Chat abierto de IA | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Mensajes de Claude | Mismo controlador (detectado automáticamente) | -| `POST /v1/responses` | Respuestas de OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Incrustaciones de OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Listado de modelos | Ruta API | -| `POST /v1/images/generations` | Imágenes de OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Listado de modelos | Ruta API | -| `POST /v1/providers/{provider}/chat/completions` | Chat abierto de IA | Dedicado por proveedor con validación de modelo | -| `POST /v1/providers/{provider}/embeddings` | Incrustaciones de OpenAI | Dedicado por proveedor con validación de modelo | -| `POST /v1/providers/{provider}/images/generations` | Imágenes de OpenAI | Dedicado por proveedor con validación de modelo | -| `POST /v1/messages/count_tokens` | Recuento de fichas de Claude | Ruta API | -| `GET /v1/models` | Lista de modelos OpenAI | Ruta API (chat + incrustación + imagen + modelos personalizados) | -| `GET /api/models/catalog` | Catálogo | Todos los modelos agrupados por proveedor + tipo | -| `POST /v1beta/models/*:streamGenerateContent` | Nativo de Géminis | Ruta API | -| `GET/PUT/DELETE /api/settings/proxy` | Configuración de proxy | Configuración del proxy de red | -| `POST /api/settings/proxy/test` | Conectividad de proxy | Punto final de prueba de conectividad/estado del proxy | -| `GET/POST/DELETE /api/provider-models` | Modelos personalizados | Gestión de modelos personalizados por proveedor | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Controlador de omisión +## Bypass Handler -El controlador de omisión (`open-sse/utils/bypassHandler.ts`) intercepta solicitudes "desechables" conocidas de Claude CLI (pings de preparación, extracciones de títulos y recuentos de tokens) y devuelve una **respuesta falsa** sin consumir tokens de proveedores ascendentes. Esto se activa solo cuando `User-Agent` contiene `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Solicitar canalización de registro +## Request Logger Pipeline -El registrador de solicitudes (`open-sse/utils/requestLogger.ts`) proporciona una canalización de registro de depuración de 7 etapas, deshabilitada de forma predeterminada y habilitada a través de `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Los archivos se escriben en `/logs//` para cada sesión de solicitud. +Files are written to `/logs//` for each request session. -## Modos de falla y resiliencia +## Failure Modes and Resilience -## 1) Disponibilidad de cuenta/proveedor +## 1) Account/Provider Availability -- tiempo de reutilización de la cuenta del proveedor en errores transitorios/de tasa/autenticación -- respaldo de la cuenta antes de fallar la solicitud -- retroceso del modelo combinado cuando se agota la ruta del modelo/proveedor actual +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Caducidad del token +## 2) Token Expiry -- verificación previa y actualización con reintento para proveedores actualizables -- Reintento 401/403 después de un intento de actualización en la ruta principal +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Seguridad de la transmisión +## 3) Stream Safety -- controlador de flujo con reconocimiento de desconexión -- flujo de traducción con descarga de final de flujo y manejo de `[DONE]` -- reserva de estimación de uso cuando faltan metadatos de uso del proveedor +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Degradación de la sincronización en la nube +## 4) Cloud Sync Degradation -- Aparecen errores de sincronización pero el tiempo de ejecución local continúa -- El programador tiene una lógica con capacidad de reintento, pero la ejecución periódica actualmente llama a la sincronización de un solo intento de forma predeterminada. +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integridad de los datos +## 5) Data Integrity -- Migración/reparación de forma de base de datos por claves faltantes -- salvaguardias de restablecimiento de JSON corruptas para localDb y useDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Observabilidad y señales operativas +## Observability and Operational Signals -Fuentes de visibilidad en tiempo de ejecución: +Runtime visibility sources: -- registros de consola de `src/sse/utils/logger.ts` -- agregados de uso por solicitud en `usage.json` -- registro de estado de solicitud textual en `log.txt` -- registros de traducción/solicitud profunda opcionales en `logs/` cuando `ENABLE_REQUEST_LOGS=true` -- puntos finales de uso del panel (`/api/usage/*`) para el consumo de UI +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Límites sensibles a la seguridad +## Security-Sensitive Boundaries -- El secreto JWT (`JWT_SECRET`) protege la verificación/firma de cookies de la sesión del panel -- La reserva de contraseña inicial (`INITIAL_PASSWORD`, predeterminada `123456`) debe anularse en implementaciones reales -- El secreto HMAC de la clave API (`API_KEY_SECRET`) protege el formato de clave API local generado -- Los secretos del proveedor (claves/tokens de API) se conservan en la base de datos local y deben protegerse a nivel del sistema de archivos. -- Los puntos finales de sincronización en la nube se basan en la semántica de autenticación de clave API + ID de máquina +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Matriz de entorno y tiempo de ejecución +## Environment and Runtime Matrix -Variables de entorno utilizadas activamente por el código: +Environment variables actively used by code: -- Aplicación/autenticación: `JWT_SECRET`, `INITIAL_PASSWORD` -- Almacenamiento: `DATA_DIR` -- Comportamiento de nodo compatible: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Anulación de la base de almacenamiento opcional (Linux/macOS cuando `DATA_DIR` no está configurado): `XDG_CONFIG_HOME` -- Hash de seguridad: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Registro: `ENABLE_REQUEST_LOGS` -- Sincronización/URL en la nube: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Proxy saliente: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` y variantes en minúsculas -- Marcas de características de SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Ayudantes de plataforma/tiempo de ejecución (no configuración específica de la aplicación): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Notas arquitectónicas conocidas +## Known Architectural Notes -1. `usageDb` y `localDb` ahora comparten la misma política de directorio base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) con la migración de archivos heredados. -2. `/api/v1/route.ts` devuelve una lista de modelos estáticos y no es la fuente principal de modelos utilizada por `/v1/models`. -3. El registrador de solicitudes escribe encabezados/cuerpo completo cuando está habilitado; trate el directorio de registro como confidencial. -4. El comportamiento de la nube depende del `NEXT_PUBLIC_BASE_URL` correcto y de la accesibilidad del punto final de la nube. -5. El directorio `open-sse/` se publica como `@omniroute/open-sse` **paquete de espacio de trabajo npm**. El código fuente lo importa a través de `@omniroute/open-sse/...` (resuelto por Next.js `transpilePackages`). Las rutas de archivo en este documento todavía usan el nombre de directorio `open-sse/` para mantener la coherencia. -6. Los gráficos en el panel utilizan **Recharts** (basados ​​en SVG) para visualizaciones analíticas interactivas y accesibles (gráficos de barras de uso de modelos, tablas de desglose de proveedores con tasas de éxito). -7. Las pruebas E2E utilizan **Dramaturgo** (`tests/e2e/`), ejecutado a través de `npm run test:e2e`. Las pruebas unitarias utilizan **ejecutor de pruebas Node.js** (`tests/unit/`), ejecutado a través de `npm run test:plan3`. El código fuente bajo `src/` es **TypeScript** (`.ts`/`.tsx`); el espacio de trabajo `open-sse/` sigue siendo JavaScript (`.js`). -8. La página de configuración está organizada en 5 pestañas: Seguridad, Enrutamiento (6 estrategias globales: completar primero, por turnos, p2c, aleatorio, menos utilizado, de costo optimizado), Resiliencia (límites de velocidad editables, disyuntor, políticas), IA (presupuesto pensado, aviso del sistema, caché de avisos), Avanzado (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Lista de verificación de verificación operativa +## Operational Verification Checklist -- Compilación desde la fuente: `npm run build` -- Crear imagen de Docker: `docker build -t omniroute .` -- Iniciar el servicio y verificar: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- La URL base de destino de CLI debe ser `http://:20128/v1` cuando `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/es/CODEBASE_DOCUMENTATION.md b/docs/i18n/es/CODEBASE_DOCUMENTATION.md index f6d5306c74..303880c198 100644 --- a/docs/i18n/es/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/es/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Documentación de la base de código +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Una guía completa y fácil de usar para principiantes sobre el enrutador proxy de IA multiproveedor **omniroute**. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. ¿Qué es omniruta? +## 1. What Is omniroute? -omniroute es un **enrutador proxy** que se encuentra entre clientes de IA (Claude CLI, Codex, Cursor IDE, etc.) y proveedores de IA (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Resuelve un gran problema: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Diferentes clientes de IA hablan diferentes "idiomas" (formatos API), y diferentes proveedores de IA también esperan "idiomas" diferentes.** omniroute traduce entre ellos automáticamente. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Piense en ello como un traductor universal en las Naciones Unidas: cualquier delegado puede hablar cualquier idioma y el traductor lo convierte para cualquier otro delegado. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Descripción general de la arquitectura +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Principio básico: traducción radial +### Core Principle: Hub-and-Spoke Translation -Toda la traducción de formatos pasa a través del **formato OpenAI como centro**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Esto significa que solo necesitas **N traductores** (uno por formato) en lugar de **N²** (cada par). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Estructura del proyecto +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Desglose módulo por módulo +## 4. Module-by-Module Breakdown -### 4.1 Configuración (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -La **única fuente de verdad** para todas las configuraciones de proveedores. +The **single source of truth** for all provider configuration. -| Archivo | Propósito | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | Objeto `PROVIDERS` con URL base, credenciales de OAuth (predeterminadas), encabezados y mensajes del sistema predeterminados para cada proveedor. También define `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` y `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Carga credenciales externas de `data/provider-credentials.json` y las combina con los valores predeterminados codificados en `PROVIDERS`. Mantiene los secretos fuera del control de código fuente y al mismo tiempo mantiene la compatibilidad con versiones anteriores. | -| `providerModels.ts` | Registro central de modelos: alias de proveedores de mapas → ID de modelos. Funciones como `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Instrucciones del sistema inyectadas en solicitudes del Codex (restricciones de edición, reglas de espacio aislado, políticas de aprobación). | -| `defaultThinkingSignature.ts` | Firmas "pensantes" predeterminadas para los modelos Claude y Gemini. | -| `ollamaModels.ts` | Definición de esquemas para modelos locales de Ollama (nombre, tamaño, familia, cuantificación). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Flujo de carga de credenciales +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Ejecutores (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Los ejecutores encapsulan **lógica específica del proveedor** utilizando el **Patrón de estrategia**. Cada ejecutor anula los métodos base según sea necesario. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Ejecutor | Proveedor | Especializaciones clave | -| ---------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Base abstracta: creación de URL, encabezados, lógica de reintento, actualización de credenciales | -| `default.ts` | Claude, Géminis, OpenAI, GLM, Kimi, MiniMax | Actualización de token genérico de OAuth para proveedores estándar | -| `antigravity.ts` | Código de la nube de Google | Generación de ID de proyecto/sesión, respaldo de múltiples URL, reintento personalizado de análisis de mensajes de error ("restablecer después de 2h7m23s") | -| `cursor.ts` | Cursor IDE | **Más complejo**: autenticación de suma de comprobación SHA-256, codificación de solicitud Protobuf, EventStream binario → análisis de respuesta SSE | -| `codex.ts` | Códice OpenAI | Inyecta instrucciones del sistema, gestiona los niveles de pensamiento, elimina parámetros no compatibles | -| `gemini-cli.ts` | CLI de Google Géminis | Creación de URL personalizada (`streamGenerateContent`), actualización del token OAuth de Google | -| `github.ts` | Copiloto de GitHub | Sistema de token dual (GitHub OAuth + token Copilot), imitación del encabezado VSCode | -| `kiro.ts` | Susurrador de códigos de AWS | Análisis binario de AWS EventStream, marcos de eventos AMZN, estimación de tokens | -| `index.ts` | — | Fábrica: nombre del proveedor de mapas → clase de ejecutor, con respaldo predeterminado | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Controladores (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -La **capa de orquestación**: coordina la traducción, la ejecución, la transmisión y el manejo de errores. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Archivo | Propósito | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Orquestador central** (~600 líneas). Maneja el ciclo de vida completo de la solicitud: detección de formato → traducción → envío del ejecutor → respuesta de transmisión/no transmisión → actualización del token → manejo de errores → registro de uso. | -| `responsesHandler.ts` | Adaptador para la API de Respuestas de OpenAI: convierte el formato de Respuestas → Finalizaciones de chat → envía a `chatCore` → convierte SSE nuevamente al formato de Respuestas. | -| `embeddings.ts` | Controlador de generación de incrustación: resuelve el modelo de incrustación → proveedor, envía la API del proveedor y devuelve una respuesta de incrustación compatible con OpenAI. Admite más de 6 proveedores. | -| `imageGeneration.ts` | Controlador de generación de imágenes: resuelve el modelo de imagen → proveedor, admite los modos compatibles con OpenAI, imagen Gemini (Antigravity) y respaldo (Nebius). Devuelve imágenes base64 o URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Solicitar ciclo de vida (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Servicios (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Lógica de negocios que soporta a los manejadores y ejecutores. +Business logic that supports the handlers and executors. -| Archivo | Propósito | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `provider.ts` | **Detección de formato** (`detectFormat`): analiza la estructura del cuerpo de la solicitud para identificar los formatos Claude/OpenAI/Gemini/Antigravity/Responses (incluye heurística `max_tokens` para Claude). Además: creación de URL, creación de encabezados, normalización de la configuración de pensamiento. Admite proveedores dinámicos `openai-compatible-*` y `anthropic-compatible-*`. | -| `model.ts` | Análisis de cadenas de modelo (`claude/model-name` → `{provider: "claude", model: "model-name"}`), resolución de alias con detección de colisiones, desinfección de entradas (rechaza el recorrido de ruta/caracteres de control) y resolución de información del modelo con soporte para captadores de alias asíncronos. | -| `accountFallback.ts` | Manejo de límite de velocidad: retroceso exponencial (1 s → 2 s → 4 s → máx. 2 min), gestión de tiempo de reutilización de la cuenta, clasificación de errores (qué errores activan el retroceso y cuáles no). | -| `tokenRefresh.ts` | Actualización del token de OAuth para **cada proveedor**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot de doble token), Kiro (AWS SSO OIDC + Social Auth). Incluye caché de deduplicación de promesa en curso y reintento con retroceso exponencial. | -| `combo.ts` | **Modelos combinados**: cadenas de modelos alternativos. Si el modelo A falla con un error elegible para respaldo, pruebe con el modelo B, luego con el C, etc. Devuelve códigos de estado ascendentes reales. | -| `usage.ts` | Obtiene datos de cuota/uso de las API del proveedor (cuotas de GitHub Copilot, cuotas del modelo Antigravity, límites de velocidad del Codex, desgloses de uso de Kiro, configuración de Claude). | -| `accountSelector.ts` | Selección inteligente de cuentas con algoritmo de puntuación: considera la prioridad, el estado de salud, la posición del round-robin y el estado de recuperación para elegir la cuenta óptima para cada solicitud. | -| `contextManager.ts` | Gestión del ciclo de vida del contexto de solicitud: crea y rastrea objetos de contexto por solicitud con metadatos (ID de solicitud, marcas de tiempo, información del proveedor) para depuración y registro. | -| `ipFilter.ts` | Control de acceso basado en IP: admite modos de lista permitida y lista de bloqueo. Valida la IP del cliente según las reglas configuradas antes de procesar las solicitudes de API. | -| `sessionManager.ts` | Seguimiento de sesiones con huellas digitales del cliente: rastrea las sesiones activas utilizando identificadores de cliente con hash, monitorea el recuento de solicitudes y proporciona métricas de sesión. | -| `signatureCache.ts` | Solicitar caché de deduplicación basada en firmas: evita solicitudes duplicadas al almacenar en caché las firmas de solicitudes recientes y devolver respuestas almacenadas en caché para solicitudes idénticas dentro de un período de tiempo. | -| `systemPrompt.ts` | Inyección de avisos del sistema global: antepone o agrega un aviso del sistema configurable a todas las solicitudes, con manejo de compatibilidad por proveedor. | -| `thinkingBudget.ts` | Gestión del presupuesto de tokens de razonamiento: admite modos de transferencia, automático (configuración de pensamiento de tira), personalizado (presupuesto fijo) y adaptativo (escalado por complejidad) para controlar los tokens de pensamiento/razonamiento. | -| `wildcardRouter.ts` | Enrutamiento de patrones de modelo comodín: resuelve patrones comodín (por ejemplo, `*/claude-*`) en pares concretos de proveedor/modelo según la disponibilidad y la prioridad. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Deduplicación de actualización de tokens +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Máquina de estado de reserva de cuenta +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Cadena de modelo combinado +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Traductor (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -El **motor de traducción de formatos** que utiliza un sistema de complementos de registro automático. +The **format translation engine** using a self-registering plugin system. -#### Arquitectura +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Directorio | Archivos | Descripción | -| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 traductores | Convierta cuerpos de solicitudes entre formatos. Cada archivo se registra automáticamente a través de `register(from, to, fn)` al importar. | -| `response/` | 7 traductores | Convierta fragmentos de respuesta de transmisión entre formatos. Maneja tipos de eventos SSE, bloques de pensamiento y llamadas a herramientas. | -| `helpers/` | 6 ayudantes | Utilidades compartidas: `claudeHelper` (extracción de avisos del sistema, configuración de pensamiento), `geminiHelper` (mapeo de partes/contenidos), `openaiHelper` (filtrado de formatos), `toolCallHelper` (generación de ID, inyección de respuestas faltantes), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Motor de traducción: `translateRequest()`, `translateResponse()`, gestión de estado, registro. | -| `formats.ts` | — | Constantes de formato: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Diseño de claves: complementos de registro automático +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Utilidades (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Archivo | Propósito | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `error.ts` | Creación de respuestas a errores (formato compatible con OpenAI), análisis de errores ascendentes, extracción en tiempo de reintento de Antigravity de mensajes de error, transmisión de errores SSE. | -| `stream.ts` | **SSE Transform Stream**: el canal principal de transmisión. Dos modos: `TRANSLATE` (traducción de formato completo) y `PASSTHROUGH` (normalizar + extraer uso). Maneja el almacenamiento en búfer de fragmentos, la estimación de uso y el seguimiento de la longitud del contenido. Las instancias de codificador/decodificador por flujo evitan el estado compartido. | -| `streamHelpers.ts` | Utilidades SSE de bajo nivel: `parseSSELine` (tolerante a espacios en blanco), `hasValuableContent` (filtra fragmentos vacíos para OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialización SSE con reconocimiento de formato con limpieza `perf_metrics`). | -| `usageTracking.ts` | Extracción de uso de tokens de cualquier formato (Claude/OpenAI/Gemini/Responses), estimación con proporciones separadas de caracteres por token de herramienta/mensaje, adición de búfer (margen de seguridad de 2000 tokens), filtrado de campos específicos del formato, registro de consola con colores ANSI. | -| `requestLogger.ts` | Registro de solicitudes basado en archivos (optar a través de `ENABLE_REQUEST_LOGS=true`). Crea carpetas de sesión con archivos numerados: `1_req_client.json` → `7_res_client.txt`. Todas las E/S son asíncronas (disparar y olvidar). Enmascara encabezados sensibles. | -| `bypassHandler.ts` | Intercepta patrones específicos de Claude CLI (extracción de títulos, calentamiento, recuento) y devuelve respuestas falsas sin llamar a ningún proveedor. Admite tanto streaming como no streaming. Limitado intencionalmente al alcance de Claude CLI. | -| `networkProxy.ts` | Resuelve la URL del proxy saliente para un proveedor determinado con prioridad: configuración específica del proveedor → configuración global → variables de entorno (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Admite exclusiones `NO_PROXY`. Configuración de cachés durante 30 segundos. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Tubería de transmisión de SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Solicitar estructura de sesión del registrador +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Capa de aplicación (`src/`) +### 4.7 Application Layer (`src/`) -| Directorio | Propósito | -| ------------- | ----------------------------------------------------------------------------------------------------- | -| `src/app/` | Interfaz de usuario web, rutas API, middleware Express, controladores de devolución de llamadas OAuth | -| `src/lib/` | Acceso a base de datos (`localDb.ts`, `usageDb.ts`), autenticación, compartido | -| `src/mitm/` | Utilidades de proxy Man-in-the-middle para interceptar el tráfico de proveedores | -| `src/models/` | Definiciones de modelos de bases de datos | -| `src/shared/` | Envoltorios de funciones open-sse (proveedor, flujo, error, etc.) | -| `src/sse/` | Controladores de puntos finales SSE que conectan la biblioteca open-sse a rutas Express | -| `src/store/` | Gestión del estado de la aplicación | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Rutas API notables +#### Notable API Routes -| Ruta | Métodos | Propósito | -| --------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | OBTENER/PUBLICAR/ELIMINAR | CRUD para modelos personalizados por proveedor | -| `/api/models/catalog` | OBTENER | Catálogo agregado de todos los modelos (chat, incrustado, imagen, personalizado) agrupados por proveedor | -| `/api/settings/proxy` | OBTENER/PONER/ELIMINAR | Configuración de proxy saliente jerárquico (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | PUBLICAR | Valida la conectividad del proxy y devuelve IP pública/latencia | -| `/v1/providers/[provider]/chat/completions` | PUBLICAR | Finalizaciones de chat dedicadas por proveedor con validación de modelo | -| `/v1/providers/[provider]/embeddings` | PUBLICAR | Incorporaciones dedicadas por proveedor con validación de modelo | -| `/v1/providers/[provider]/images/generations` | PUBLICAR | Generación de imágenes dedicada por proveedor con validación de modelo | -| `/api/settings/ip-filter` | OBTENER/PONER | Gestión de listas de IP permitidas/bloqueadas | -| `/api/settings/thinking-budget` | OBTENER/PONER | Configuración del presupuesto del token de razonamiento (transferencia/automático/personalizado/adaptativo) | -| `/api/settings/system-prompt` | OBTENER/PONER | Inyección rápida del sistema global para todas las solicitudes | -| `/api/sessions` | OBTENER | Seguimiento y métricas de sesiones activas | -| `/api/rate-limits` | OBTENER | Estado del límite de tasa por cuenta | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Patrones de diseño clave +## 5. Key Design Patterns -### 5.1 Traducción radial +### 5.1 Hub-and-Spoke Translation -Todos los formatos se traducen a través del **formato OpenAI como centro**. Agregar un nuevo proveedor solo requiere escribir **un par** de traductores (hacia/desde OpenAI), no N pares. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Patrón de estrategia del ejecutor +### 5.2 Executor Strategy Pattern -Cada proveedor tiene una clase de ejecutor dedicada que hereda de `BaseExecutor`. La fábrica en `executors/index.ts` selecciona la correcta en tiempo de ejecución. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Sistema de complementos de autorregistro +### 5.3 Self-Registering Plugin System -Los módulos traductores se registran al importar a través de `register()`. Agregar un nuevo traductor es simplemente crear un archivo e importarlo. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Reserva de cuenta con retroceso exponencial +### 5.4 Account Fallback with Exponential Backoff -Cuando un proveedor devuelve 429/401/500, el sistema puede cambiar a la siguiente cuenta, aplicando tiempos de reutilización exponenciales (1 s → 2 s → 4 s → máx. 2 min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Cadenas de modelos combinados +### 5.5 Combo Model Chains -Un "combo" agrupa varias cadenas `provider/model`. Si el primero falla, se pasa automáticamente al siguiente. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Traducción de transmisión con estado +### 5.6 Stateful Streaming Translation -La traducción de respuestas mantiene el estado en todos los fragmentos de SSE (seguimiento de bloques de pensamiento, acumulación de llamadas de herramientas, indexación de bloques de contenido) a través del mecanismo `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Búfer de seguridad de uso +### 5.7 Usage Safety Buffer -Se agrega un búfer de 2000 tokens al uso informado para evitar que los clientes alcancen los límites de la ventana de contexto debido a la sobrecarga de las indicaciones del sistema y la traducción de formato. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Formatos admitidos +## 6. Supported Formats -| Formato | Dirección | Identificador | -| ------------------------------ | ---------------- | ------------------ | -| Finalizaciones del chat OpenAI | fuente + destino | `openai` | -| API de respuestas OpenAI | fuente + destino | `openai-responses` | -| Claude antrópico | fuente + destino | `claude` | -| Google Géminis | fuente + destino | `gemini` | -| CLI de Google Géminis | sólo objetivo | `gemini-cli` | -| Antigravedad | fuente + destino | `antigravity` | -| AWS Kiro | sólo objetivo | `kiro` | -| Cursores | sólo objetivo | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Proveedores admitidos +## 7. Supported Providers -| Proveedor | Método de autenticación | Ejecutor | Notas clave | -| ------------------------ | ------------------------------------- | -------------- | --------------------------------------------------------------- | -| Claude antrópico | Clave API u OAuth | Predeterminado | Utiliza el encabezado `x-api-key` | -| Google Géminis | Clave API u OAuth | Predeterminado | Utiliza el encabezado `x-goog-api-key` | -| CLI de Google Géminis | OAuth | GéminisCLI | Utiliza el punto final `streamGenerateContent` | -| Antigravedad | OAuth | Antigravedad | Respaldo de múltiples URL, análisis de reintentos personalizado | -| Abierta AI | Clave API | Predeterminado | Autenticación de abanderado | -| Códice | OAuth | Códice | Inyecta instrucciones del sistema, gestiona el pensamiento | -| Copiloto de GitHub | OAuth + token de copiloto | GitHub | Token dual, imitación del encabezado VSCode | -| Kiro (AWS) | AWS SSO OIDC o redes sociales | kiro | Análisis binario de EventStream | -| Cursor IDE | Autenticación de suma de comprobación | Cursores | Codificación Protobuf, sumas de comprobación SHA-256 | -| Qwen | OAuth | Predeterminado | Autenticación estándar | -| iFlujo | OAuth (Básico + Portador) | Predeterminado | Encabezado de autenticación dual | -| Enrutador abierto | Clave API | Predeterminado | Autenticación de abanderado | -| GLM, Kimi, MiniMax | Clave API | Predeterminado | Compatible con Claude, use `x-api-key` | -| `openai-compatible-*` | Clave API | Predeterminado | Dinámico: cualquier punto final compatible con OpenAI | -| `anthropic-compatible-*` | Clave API | Predeterminado | Dinámico: cualquier punto final compatible con Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Resumen del flujo de datos +## 8. Data Flow Summary -### Solicitud de transmisión +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Solicitud sin transmisión +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Flujo de derivación (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/es/FEATURES.md b/docs/i18n/es/FEATURES.md index 4003096b20..82cc73b67b 100644 --- a/docs/i18n/es/FEATURES.md +++ b/docs/i18n/es/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Galería de funciones del panel +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Guía visual de cada sección del panel de OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Proveedores +## 🔌 Providers -Administre las conexiones de proveedores de IA: proveedores de OAuth (Claude Code, Codex, Gemini CLI), proveedores de claves API (Groq, DeepSeek, OpenRouter) y proveedores gratuitos (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨Combinaciones +## 🎨 Combos -Cree combinaciones de enrutamiento de modelos con 6 estrategias: llenar primero, por turnos, poder de dos opciones, aleatorio, menos utilizado y de costo optimizado. Cada combo encadena múltiples modelos con respaldo automático. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Análisis +## 📊 Analytics -Análisis de uso integral con consumo de tokens, estimaciones de costos, mapas de actividad, gráficos de distribución semanal y desgloses por proveedor. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Salud del sistema +## 🏥 System Health -Monitoreo en tiempo real: tiempo de actividad, memoria, versión, percentiles de latencia (p50/p95/p99), estadísticas de caché y estados de los disyuntores del proveedor. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Patio de juegos del traductor +## 🔧 Translator Playground -Cuatro modos para depurar traducciones de API: **Playground** (convertidor de formato), **Chat Tester** (solicitudes en vivo), **Test Bench** (pruebas por lotes) y **Live Monitor** (transmisión en tiempo real). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Configuración +## 🎮 Model Playground _(v2.0.9+)_ -Configuración general, almacenamiento del sistema, administración de copias de seguridad (exportación/importación de base de datos), apariencia (modo oscuro/claro), seguridad (incluye protección de terminales API y bloqueo de proveedores personalizado), enrutamiento, resiliencia y configuración avanzada. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Herramientas CLI +## 🔧 CLI Tools -Configuración con un clic para herramientas de codificación de IA: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code y Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Solicitar registros +## 🤖 CLI Agents _(v2.0.11+)_ -Registro de solicitudes en tiempo real con filtrado por proveedor, modelo, cuenta y clave API. Muestra códigos de estado, uso de token, latencia y detalles de respuesta. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Punto final API +## 🌐 API Endpoint -Su punto final API unificado con desglose de capacidades: finalización de chat, incrustaciones, generación de imágenes, reclasificación, transcripción de audio y claves API registradas. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/es/TROUBLESHOOTING.md b/docs/i18n/es/TROUBLESHOOTING.md index 07b88bf54c..120092d63c 100644 --- a/docs/i18n/es/TROUBLESHOOTING.md +++ b/docs/i18n/es/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Solución de problemas +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Problemas comunes y soluciones para OmniRoute. +Common problems and solutions for OmniRoute. --- -## Soluciones rápidas +## Quick Fixes -| Problema | Solución | -| ------------------------------------------ | ---------------------------------------------------------------------------------------------- | -| El primer inicio de sesión no funciona | Marque `INITIAL_PASSWORD` en `.env` (predeterminado: `123456`) | -| El panel se abre en el puerto incorrecto | Establecer `PORT=20128` y `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No hay registros de solicitudes en `logs/` | Establecer `ENABLE_REQUEST_LOGS=true` | -| EACCES: permiso denegado | Establezca `DATA_DIR=/path/to/writable/dir` para anular `~/.omniroute` | -| La estrategia de enrutamiento no se guarda | Actualización a v1.4.11+ (corrección del esquema Zod para la persistencia de la configuración) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Problemas con el proveedor +## Provider Issues -### "El modelo de idioma no proporcionó mensajes" +### "Language model did not provide messages" -**Causa:** Cuota de proveedor agotada. +**Cause:** Provider quota exhausted. -**Arreglo:** +**Fix:** -1. Verifique el rastreador de cuotas del panel -2. Utilice un combo con niveles alternativos -3. Cambiar al nivel más barato/gratuito +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Limitación de velocidad +### Rate Limiting -**Causa:** Cuota de suscripción agotada. +**Cause:** Subscription quota exhausted. -**Arreglo:** +**Fix:** -- Agregar respaldo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Utilice GLM/MiniMax como copia de seguridad económica +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### El token de OAuth ha caducado +### OAuth Token Expired -OmniRoute actualiza automáticamente los tokens. Si los problemas persisten: +OmniRoute auto-refreshes tokens. If issues persist: -1. Panel de control → Proveedor → Reconectar -2. Eliminar y volver a agregar la conexión del proveedor. +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Problemas con la nube +## Cloud Issues -### Errores de sincronización en la nube +### Cloud Sync Errors -1. Verifique que `BASE_URL` apunte a su instancia en ejecución (por ejemplo, `http://localhost:20128`) -2. Verifique que `CLOUD_URL` apunte a su punto final en la nube (por ejemplo, `https://omniroute.dev`). -3. Mantenga los valores `NEXT_PUBLIC_*` alineados con los valores del lado del servidor +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Nube `stream=false` Devuelve 500 +### Cloud `stream=false` Returns 500 -**Síntoma:** `Unexpected token 'd'...` en el punto final de la nube para llamadas que no son de transmisión. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Causa:** Upstream devuelve la carga útil SSE mientras que el cliente espera JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Solución alternativa:** Utilice `stream=true` para llamadas directas en la nube. El tiempo de ejecución local incluye el respaldo SSE → JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### La nube dice Conectada pero "Clave API no válida" +### Cloud Says Connected but "Invalid API key" -1. Cree una clave nueva desde el panel local (`/api/keys`) -2. Ejecute la sincronización en la nube: Habilitar nube → Sincronizar ahora -3. Las claves antiguas o no sincronizadas aún pueden devolver `401` en la nube +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Problemas con Docker +## Docker Issues -### La herramienta CLI muestra no instalada +### CLI Tool Shows Not Installed -1. Verifique los campos de tiempo de ejecución: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Para el modo portátil: use el destino de imagen `runner-cli` (CLI incluidas) -3. Para el modo de montaje del host: configure `CLI_EXTRA_PATHS` y monte el directorio bin del host como de solo lectura -4. Si `installed=true` y `runnable=false`: se encontró el binario pero falló la verificación de estado +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Validación rápida del tiempo de ejecución +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Problemas de costos +## Cost Issues -### Altos costos +### High Costs -1. Verifique las estadísticas de uso en Panel → Uso -2. Cambie el modelo principal a GLM/MiniMax -3. Utilice el nivel gratuito (Gemini CLI, iFlow) para tareas no críticas -4. Establezca presupuestos de costos por clave API: Panel → Claves API → Presupuesto +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Depuración +## Debugging -### Habilitar registros de solicitudes +### Enable Request Logs -Establezca `ENABLE_REQUEST_LOGS=true` en su archivo `.env`. Los registros aparecen en el directorio `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Verificar el estado del proveedor +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Almacenamiento en tiempo de ejecución +### Runtime Storage -- Estado principal: `${DATA_DIR}/db.json` (proveedores, combos, alias, claves, configuraciones) -- Uso: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Solicitar registros: `/logs/...` (cuando `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Problemas con el disyuntor +## Circuit Breaker Issues -### Proveedor atascado en estado ABIERTO +### Provider stuck in OPEN state -Cuando el disyuntor de un proveedor está ABIERTO, las solicitudes se bloquean hasta que expire el tiempo de reutilización. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Arreglo:** +**Fix:** -1. Vaya a **Panel → Configuración → Resiliencia** -2. Verifique la tarjeta del disyuntor del proveedor afectado. -3. Haga clic en **Restablecer todo** para borrar todos los interruptores o espere a que expire el tiempo de reutilización. -4. Verifique que el proveedor esté realmente disponible antes de restablecer +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### El proveedor sigue disparando el disyuntor +### Provider keeps tripping the circuit breaker -Si un proveedor ingresa repetidamente al estado ABIERTO: +If a provider repeatedly enters OPEN state: -1. Marque **Panel → Estado → Estado del proveedor** para ver el patrón de error. -2. Vaya a **Configuración → Resiliencia → Perfiles de proveedores** y aumente el umbral de falla. -3. Verifique si el proveedor ha cambiado los límites de API o requiere una nueva autenticación. -4. Revise la telemetría de latencia: una latencia alta puede causar fallas basadas en el tiempo de espera +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problemas de transcripción de audio +## Audio Transcription Issues -### Error "Modelo no compatible" +### "Unsupported model" error -- Asegúrate de estar usando el prefijo correcto: `deepgram/nova-3` o `assemblyai/best` -- Verifique que el proveedor esté conectado en **Panel → Proveedores** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### La transcripción vuelve vacía o falla +### Transcription returns empty or fails -- Verifique los formatos de audio admitidos: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Verifique que el tamaño del archivo esté dentro de los límites del proveedor (normalmente < 25 MB) -- Verifique la validez de la clave API del proveedor en la tarjeta del proveedor +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Depuración del traductor +## Translator Debugging -Utilice **Panel → Traductor** para depurar problemas de traducción de formato: +Use **Dashboard → Translator** to debug format translation issues: -| Modo | Cuándo utilizar | -| -------------------------- | ------------------------------------------------------------------------------------------------------------- | -| **Parque infantil** | Compare formatos de entrada/salida uno al lado del otro: pegue una solicitud fallida para ver cómo se traduce | -| **Probador de chat** | Envíe mensajes en vivo e inspeccione la carga útil completa de solicitud/respuesta, incluidos los encabezados | -| **Banco de pruebas** | Ejecute pruebas por lotes en combinaciones de formatos para encontrar qué traducciones no funcionan | -| **Monitorización en vivo** | Observe el flujo de solicitudes en tiempo real para detectar problemas de traducción intermitentes | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Problemas comunes de formato +### Common format issues -- **Las etiquetas de pensamiento no aparecen**: compruebe si el proveedor objetivo apoya el pensamiento y la configuración del presupuesto de pensamiento. -- **Caídas de llamadas a herramientas**: algunas traducciones de formatos pueden eliminar campos no admitidos; verificar en modo Patio de Juegos -- **Falta el mensaje del sistema**: Claude y Gemini manejan los mensajes del sistema de manera diferente; comprobar la salida de la traducción -- **El SDK devuelve una cadena sin formato en lugar de un objeto** — Corregido en v1.1.0: el desinfectante de respuesta ahora elimina los campos no estándar (`x_groq`, `usage_breakdown`, etc.) que causan fallas de validación de Pydantic en el SDK de OpenAI -- **GLM/ERNIE rechaza el rol `system`** — Corregido en v1.1.0: el normalizador de roles fusiona automáticamente los mensajes del sistema con mensajes de usuario para modelos incompatibles -- **`developer` rol no reconocido** — Corregido en v1.1.0: convertido automáticamente a `system` para proveedores que no son OpenAI -- **`json_schema` no funciona con Gemini** — Corregido en v1.1.0: `response_format` ahora se convierte a `responseMimeType` + `responseSchema` de Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Configuración de resiliencia +## Resilience Settings -### El límite de velocidad automático no se activa +### Auto rate-limit not triggering -- El límite de velocidad automático solo se aplica a los proveedores de claves API (no a OAuth/suscripción) -- Verifique que **Configuración → Resiliencia → Perfiles de proveedores** tenga habilitado el límite de tasa automática -- Compruebe si el proveedor devuelve códigos de estado `429` o encabezados `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Ajuste del retroceso exponencial +### Tuning exponential backoff -Los perfiles de proveedor admiten estas configuraciones: +Provider profiles support these settings: -- **Retraso base**: tiempo de espera inicial después del primer fallo (predeterminado: 1 s) -- **Retraso máximo**: límite máximo de tiempo de espera (predeterminado: 30 segundos) -- **Multiplicador**: cuánto aumentar el retraso por falla consecutiva (predeterminado: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Manada anti-truenos +### Anti-thundering herd -Cuando muchas solicitudes simultáneas llegan a un proveedor de velocidad limitada, OmniRoute utiliza mutex + limitación de velocidad automática para serializar solicitudes y evitar fallas en cascada. Esto es automático para los proveedores de claves API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## ¿Sigues atascado? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Problemas de GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arquitectura**: consulte [link](ARCHITECTURE.md) para obtener detalles internos -- **Referencia de API**: consulte [link](API_REFERENCE.md) para conocer todos los puntos finales -- **Panel de estado**: marque **Panel → Salud** para ver el estado del sistema en tiempo real -- **Traductor**: use **Panel → Traductor** para depurar problemas de formato +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/es/USER_GUIDE.md b/docs/i18n/es/USER_GUIDE.md index f24275870b..5a043224df 100644 --- a/docs/i18n/es/USER_GUIDE.md +++ b/docs/i18n/es/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Guía del usuario +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Guía completa para configurar proveedores, crear combos, integrar herramientas CLI e implementar OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Tabla de contenidos +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Guía completa para configurar proveedores, crear combos, integrar herramientas --- -## 💰 Precios de un vistazo +## 💰 Pricing at a Glance -| Nivel | Proveedor | Costo | Restablecer cuota | Mejor para | -| ------------------ | ---------------------- | -------------------- | ----------------------------- | --------------------------- | -| **💳 SUSCRIPCIÓN** | Código Claude (Pro) | $20/mes | 5h + weekly | Ya suscrito | -| | Códice (Plus/Pro) | $20-200/mes | 5h + semanales | Usuarios de OpenAI | -| | Géminis CLI | **GRATIS** | 180K/mes + 1K/día | ¡Todos! | -| | Copiloto de GitHub | $10-19/mes | Mensual | Usuarios de GitHub | -| **🔑 CLAVE API** | Búsqueda profunda | Pago por uso | Ninguno | Razonamiento barato | -| | Groq | Pago por uso | Ninguno | Inferencia ultrarrápida | -| | xAI (Grok) | Pago por uso | Ninguno | Grok 4 razonamiento | -| | Mistral | Pago por uso | Ninguno | Modelos alojados en la UE | -| | Perplejidad | Pago por uso | Ninguno | Búsqueda aumentada | -| | Juntos IA | Pago por uso | Ninguno | Modelos de código abierto | -| | Fuegos artificiales AI | Pago por uso | Ninguno | Imágenes de flujo rápido | -| | Cerebras | Pago por uso | None | Velocidad a escala de oblea | -| | Coherir | Pago por uso | Ninguno | Comando R+ TRAPO | -| | NIM de NVIDIA | Pago por uso | Ninguno | Modelos empresariales | -| **💰 BARATO** | GLM-4.7 | 0,6 dólares/1 millón | Todos los días a las 10 a. m. | Respaldo presupuestario | -| | MiniMax M2.1 | 0,2 dólares/1 millón | 5 horas rodantes | Opción más barata | -| | Kimi K2 | $9/mes fijo | 10 millones de tokens/mes | Costo predecible | -| **🆓 GRATIS** | iFlujo | $0 | Ilimitado | 8 modelos gratis | -| | Qwen | $0 | Ilimitado | 3 modelos gratis | -| | kiro | $0 | Ilimitado | Claudio libre | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Consejo profesional:** Comience con el combo Gemini CLI (180 000 gratis/mes) + iFlow (ilimitado y gratis) = ¡Costo de $0! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Casos de uso +## 🎯 Use Cases -### Caso 1: "Tengo una suscripción a Claude Pro" +### Case 1: "I have Claude Pro subscription" -**Problema:** La cuota vence sin usarse, la tasa se limita durante la codificación intensa +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Caso 2: "Quiero coste cero" +### Case 2: "I want zero cost" -**Problema:** No puedo permitirme suscripciones, necesito codificación de IA confiable +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Caso 3: "Necesito codificación 24 horas al día, 7 días a la semana, sin interrupciones" +### Case 3: "I need 24/7 coding, no interruptions" -**Problema:** Plazos, no puedo permitirme el tiempo de inactividad +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Caso 4: "Quiero IA GRATIS en OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Problema:** Necesita asistente de IA en aplicaciones de mensajería, completamente gratis +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Configuración del proveedor +## 📖 Provider Setup -### 🔐 Proveedores de suscripción +### 🔐 Subscription Providers -#### Código Claude (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Consejo profesional:** Utilice Opus para tareas complejas y Sonnet para mayor velocidad. ¡OmniRoute realiza un seguimiento de la cuota por modelo! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### Códice OpenAI (Plus/Pro) +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (¡180K GRATIS/mes!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Mejor valor:** ¡Enorme nivel gratuito! Utilice esto antes de los niveles pagos. +**Best Value:** Huge free tier! Use this before paid tiers. -#### Copiloto de GitHub +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Proveedores baratos +### 💰 Cheap Providers -#### GLM-4.7 (Restablecimiento diario, $0,6/1 millón) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Regístrate: [Zhipu AI](https://open.bigmodel.cn/) -2. Obtenga la clave API del plan de codificación -3. Panel de control → Agregar clave API: Proveedor: `glm`, Clave API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Uso:** `glm/glm-4.7` — **Consejo profesional:** ¡El plan de codificación ofrece 3 × cuota a 1/7 de costo! Reiniciar diariamente a las 10:00 a.m. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (reinicio de 5 h, $0,20/1 millón) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Regístrate: [MiniMax](https://www.minimax.io/) -2. Obtener clave API → Panel → Agregar clave API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Uso:** `minimax/MiniMax-M2.1` — **Consejo profesional:** ¡La opción más barata para contexto largo (1 millón de tokens)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/mes fijo) +#### Kimi K2 ($9/month flat) -1. Suscríbete: [Moonshot AI](https://platform.moonshot.ai/) -2. Obtener clave API → Panel → Agregar clave API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Uso:** `kimi/kimi-latest` — **Consejo profesional:** ¡Fijo $9/mes por 10 millones de tokens = $0,90/1 millón de costo efectivo! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 Proveedores GRATIS +### 🆓 FREE Providers -#### iFlow (8 modelos GRATIS) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 modelos GRATIS) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRATIS) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨Combinaciones +## 🎨 Combos -### Ejemplo 1: Maximizar la suscripción → Copia de seguridad económica +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Ejemplo 2: Solo gratuito (coste cero) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,7 +249,7 @@ Cost: $0 forever! --- -## 🔧 Integración CLI +## 🔧 CLI Integration ### Cursor IDE @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Código Claude +### Claude Code -Editar `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Editar `~/.claude/config.json`: } ``` -### CLI del Códice +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -279,9 +279,9 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### Garra Abierta +### OpenClaw -Editar `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Editar `~/.openclaw/openclaw.json`: } ``` -**O use el Panel:** Herramientas CLI → OpenClaw → Configuración automática +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Continuar / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Implementación +## 🚀 Deployment -### Implementación de VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### acoplador +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,53 +403,56 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Para el modo integrado en el host con binarios CLI, consulte la sección Docker en los documentos principales. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Variables de entorno +### Environment Variables -| Variables | Predeterminado | Descripción | -| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------ | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Secreto de firma de JWT (**cambio en producción**) | -| `INITIAL_PASSWORD` | `123456` | Primera contraseña de inicio de sesión | -| `DATA_DIR` | `~/.omniroute` | Directorio de datos (db, uso, registros) | -| `PORT` | marco predeterminado | Puerto de servicio (`20128` en ejemplos) | -| `HOSTNAME` | marco predeterminado | Vincular host (Docker por defecto es `0.0.0.0`) | -| `NODE_ENV` | valor predeterminado de tiempo de ejecución | Establecer `production` para implementación | -| `BASE_URL` | `http://localhost:20128` | URL base interna del lado del servidor | -| `CLOUD_URL` | `https://omniroute.dev` | URL base del punto final de sincronización en la nube | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Secreto HMAC para claves API generadas | -| `REQUIRE_API_KEY` | `false` | Aplicar la clave API de portador en `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Habilita registros de solicitud/respuesta | -| `AUTH_COOKIE_SECURE` | `false` | Forzar cookie de autenticación `Secure` (detrás del proxy inverso HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Para obtener la referencia completa de las variables de entorno, consulte [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Modelos disponibles +## 📊 Available Models
-Ver todos los modelos disponibles +View all available models -**Código Claude (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Códice (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Copilot de GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — 0,6 $/1 millón: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $0,2/1 millón: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` -** Búsqueda profunda (`ds/`) **: `ds/deepseek-chat`, `ds/deepseek-reasoner` +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` **Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` @@ -401,15 +460,15 @@ Para obtener la referencia completa de las variables de entorno, consulte [READM **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Perplejidad (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Juntos AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Fuegos artificiales AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` **Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Coherir (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Para obtener la referencia completa de las variables de entorno, consulte [READM --- -## 🧩 Funciones avanzadas +## 🧩 Advanced Features -### Modelos personalizados +### Custom Models -Agregue cualquier ID de modelo a cualquier proveedor sin esperar una actualización de la aplicación: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -O utilice el Panel de control: **Proveedores → [Proveedor] → Modelos personalizados**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Rutas de proveedores dedicadas +### Dedicated Provider Routes -Enrutar solicitudes directamente a un proveedor específico con validación de modelo: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -El prefijo del proveedor se agrega automáticamente si falta. Los modelos no coincidentes devuelven `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Configuración del proxy de red +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Precedencia:** Específico de clave → Específico de combo → Específico de proveedor → Global → Entorno. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API del catálogo de modelos +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Devuelve modelos agrupados por proveedor con tipos (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Sincronización en la nube +### Cloud Sync -- Sincronizar proveedores, combos y configuraciones entre dispositivos -- Sincronización automática en segundo plano con tiempo de espera + falla rápida -- Prefiere `BASE_URL`/`CLOUD_URL` del lado del servidor en producción +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (Fase 9) +### LLM Gateway Intelligence (Phase 9) -- **Caché semántica**: cachés automáticos sin transmisión, temperatura = 0 respuestas (omitir con `X-OmniRoute-No-Cache: true`) -- **Idempotencia de solicitud**: deduplica solicitudes en 5 segundos a través del encabezado `Idempotency-Key` o `X-Request-Id` -- **Seguimiento del progreso**: suscripción a eventos SSE `event: progress` a través del encabezado `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Patio de juegos del traductor +### Translator Playground -Acceda a través de **Panel → Traductor**. Depure y visualice cómo OmniRoute traduce las solicitudes de API entre proveedores. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Modo | Propósito | -| -------------------------- | -------------------------------------------------------------------------------------------------------------- | -| **Parque infantil** | Seleccione formatos de origen/destino, pegue una solicitud y vea el resultado traducido al instante | -| **Probador de chat** | Envíe mensajes de chat en vivo a través del proxy e inspeccione el ciclo completo de solicitud/respuesta | -| **Banco de pruebas** | Ejecute pruebas por lotes en múltiples combinaciones de formatos para verificar la corrección de la traducción | -| **Monitorización en vivo** | Vea traducciones en tiempo real a medida que las solicitudes fluyen a través del proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Casos de uso:** +**Use cases:** -- Depurar por qué falla una combinación específica de cliente/proveedor -- Verificar que las etiquetas de pensamiento, las llamadas a herramientas y las indicaciones del sistema se traduzcan correctamente -- Compare las diferencias de formato entre los formatos OpenAI, Claude, Gemini y Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Estrategias de enrutamiento +### Routing Strategies -Configure a través de **Panel → Configuración → Enrutamiento**. +Configure via **Dashboard → Settings → Routing**. -| Estrategia | Descripción | -| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -| **Llene primero** | Utiliza cuentas en orden de prioridad: la cuenta principal maneja todas las solicitudes hasta que no esté disponible | -| **Round Robin** | Recorre todas las cuentas con un límite fijo configurable (predeterminado: 3 llamadas por cuenta) | -| **P2C (Poder de dos opciones)** | Elige 2 cuentas al azar y ruta hacia la más saludable: los saldos se cargan con conciencia de la salud | -| **Aleatorio** | Selecciona aleatoriamente una cuenta para cada solicitud mediante la reproducción aleatoria de Fisher-Yates | -| **Menos usado** | Rutas a la cuenta con la marca de tiempo `lastUsedAt` más antigua, distribuyendo el tráfico de manera uniforme | -| **Costo optimizado** | Rutas a la cuenta con el valor de prioridad más bajo, optimizando para proveedores de menor costo | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Alias de modelo comodín +#### Wildcard Model Aliases -Cree patrones comodín para reasignar nombres de modelos: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Los comodines admiten `*` (cualquier carácter) y `?` (un solo carácter). +Wildcards support `*` (any characters) and `?` (single character). -#### Cadenas de respaldo +#### Fallback Chains -Defina cadenas de respaldo globales que se apliquen a todas las solicitudes: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Resiliencia y disyuntores +### Resilience & Circuit Breakers -Configure a través de **Panel → Configuración → Resiliencia**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementa resiliencia a nivel de proveedor con cuatro componentes: +OmniRoute implements provider-level resilience with four components: -1. **Perfiles de proveedor**: configuración por proveedor para: - - Umbral de fallas (cuántas fallas antes de abrir) - - Duración del tiempo de recuperación - - Sensibilidad de detección de límite de velocidad - - Parámetros de retroceso exponencial +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Límites de tarifas editables**: valores predeterminados a nivel del sistema configurables en el panel: - - **Solicitudes por minuto (RPM)**: solicitudes máximas por minuto por cuenta - - **Tiempo mínimo entre solicitudes**: intervalo mínimo en milisegundos entre solicitudes - - **Máximo de solicitudes simultáneas**: máximo de solicitudes simultáneas por cuenta - - Haga clic en **Editar** para modificar y luego en **Guardar** o **Cancelar**. Los valores persisten a través de la API de resiliencia. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Disyuntor**: realiza un seguimiento de las fallas por proveedor y abre automáticamente el circuito cuando se alcanza un umbral: - - **CERRADO** (En buen estado): las solicitudes fluyen normalmente - - **ABIERTO**: el proveedor está bloqueado temporalmente después de fallas repetidas - - **HALF_OPEN** — Probando si el proveedor se ha recuperado +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Políticas e identificadores bloqueados**: muestra el estado del disyuntor y los identificadores bloqueados con capacidad de desbloqueo forzado. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Detección automática de límite de tasa**: monitorea los encabezados `429` y `Retry-After` para evitar de manera proactiva alcanzar los límites de tasa del proveedor. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Consejo profesional:** Utilice el botón **Restablecer todo** para borrar todos los disyuntores y tiempos de reutilización cuando un proveedor se recupera de una interrupción. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Exportación/Importación de base de datos +### Database Export / Import -Administre las copias de seguridad de la base de datos en **Panel → Configuración → Sistema y almacenamiento**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Acción | Descripción | -| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Exportar base de datos** | Descarga la base de datos SQLite actual como un archivo `.sqlite` | -| **Exportar todo (.tar.gz)** | Descarga un archivo de copia de seguridad completo que incluye: base de datos, configuraciones, combinaciones, conexiones de proveedores (sin credenciales), metadatos de clave API | -| **Importar base de datos** | Cargue un archivo `.sqlite` para reemplazar la base de datos actual. Se crea automáticamente una copia de seguridad previa a la importación | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Validación de importación:** Se valida la integridad del archivo importado (verificación de pragma de SQLite), las tablas requeridas (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) y el tamaño (máximo 100 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Casos de uso:** +**Use Cases:** -- Migrar OmniRoute entre máquinas -- Crear copias de seguridad externas para la recuperación de desastres. -- Compartir configuraciones entre los miembros del equipo (exportar todo → compartir archivo) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Panel de configuración +### Settings Dashboard -La página de configuración está organizada en 5 pestañas para facilitar la navegación: +The settings page is organized into 5 tabs for easy navigation: -| Pestaña | Contenidos | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| **Seguridad** | Configuración de inicio de sesión/contraseña, control de acceso IP, autenticación API para `/models` y bloqueo de proveedores | -| **Enrutamiento** | Estrategia de enrutamiento global (6 opciones), alias de modelos comodín, cadenas de respaldo, valores predeterminados combinados | -| **Resiliencia** | Perfiles de proveedores, límites de tarifas editables, estado de los disyuntores, políticas e identificadores bloqueados | -| **IA** | Pensando en la configuración del presupuesto, inyección de avisos del sistema global, estadísticas de caché de avisos | -| **Avanzado** | Configuración de proxy global (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Gestión de costes y presupuesto +### Costs & Budget Management -Acceso a través de **Panel → Costos**. +Access via **Dashboard → Costs**. -| Pestaña | Propósito | -| --------------- | ------------------------------------------------------------------------------------------------------------------- | -| **Presupuesto** | Establezca límites de gasto por clave API con presupuestos diarios/semanales/mensuales y seguimiento en tiempo real | -| **Precios** | Ver y editar entradas de precios de modelos: costo por 1.000 tokens de entrada/salida por proveedor | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Seguimiento de costos:** Cada solicitud registra el uso del token y calcula el costo utilizando la tabla de precios. Vea desgloses en **Panel → Uso** por proveedor, modelo y clave API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Transcripción de audio +### Audio Transcription -OmniRoute admite la transcripción de audio a través del punto final compatible con OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Proveedores disponibles: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Formatos de audio admitidos: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Estrategias de equilibrio combinadas +### Combo Balancing Strategies -Configure el equilibrio por combo en **Panel → Combos → Crear/Editar → Estrategia**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Estrategia | Descripción | -| -------------------------- | -------------------------------------------------------------------------------------------- | -| **Todos contra todos** | Gira a través de modelos secuencialmente | -| **Prioridad** | Siempre prueba el primer modelo; retrocede sólo en caso de error | -| **Aleatorio** | Elige un modelo aleatorio del combo para cada solicitud | -| **Ponderado** | Rutas proporcionalmente en función de los pesos asignados por modelo | -| **Menos usado** | Rutas al modelo con la menor cantidad de solicitudes recientes (utiliza métricas combinadas) | -| **Optimización de costos** | Rutas al modelo más barato disponible (utiliza tabla de precios) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Los valores predeterminados combinados globales se pueden configurar en **Panel → Configuración → Enrutamiento → Valores predeterminados combinados**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Panel de salud +### Health Dashboard -Accede a través de **Panel → Salud**. Descripción general del estado del sistema en tiempo real con 6 tarjetas: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Tarjeta | Lo que muestra | -| -------------------------- | --------------------------------------------------------------------------------- | -| **Estado del sistema** | Tiempo de actividad, versión, uso de memoria, directorio de datos | -| **Salud del proveedor** | Estado del disyuntor por proveedor (cerrado/abierto/medio abierto) | -| **Límites de tarifas** | Tiempos de reutilización del límite de tasa activa por cuenta con tiempo restante | -| **Bloqueos activos** | Proveedores bloqueados temporalmente por la política de bloqueo | -| **Caché de firma** | Estadísticas de caché de deduplicación (claves activas, tasa de aciertos) | -| **Telemetría de latencia** | Agregación de latencia p50/p95/p99 por proveedor | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Consejo profesional:** La página Salud se actualiza automáticamente cada 10 segundos. Utilice la tarjeta del disyuntor para identificar qué proveedores están experimentando problemas. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/fi/API_REFERENCE.md b/docs/i18n/fi/API_REFERENCE.md index 3ebeae0b5e..b795722c11 100644 --- a/docs/i18n/fi/API_REFERENCE.md +++ b/docs/i18n/fi/API_REFERENCE.md @@ -1,12 +1,12 @@ -# API-viite +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Täydellinen viite kaikille OmniRoute API -päätepisteille. +Complete reference for all OmniRoute API endpoints. --- -## Sisällysluettelo +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Täydellinen viite kaikille OmniRoute API -päätepisteille. --- -## Chatin valmistuminen +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Mukautetut otsikot +### Custom Headers -| Otsikko | Suunta | Kuvaus | -| ------------------------ | ------- | ----------------------------------------- | -| `X-OmniRoute-No-Cache` | Pyyntö | Aseta `true` ohittaaksesi välimuistin | -| `X-OmniRoute-Progress` | Pyyntö | Aseta arvoon `true` edistymistapahtumille | -| `Idempotency-Key` | Pyyntö | Dedup-avain (5s ikkuna) | -| `X-Request-Id` | Pyyntö | Vaihtoehtoinen dedup-avain | -| `X-OmniRoute-Cache` | Vastaus | `HIT` tai `MISS` (ei suoratoistoa) | -| `X-OmniRoute-Idempotent` | Vastaus | `true` jos kopiointi poistetaan | -| `X-OmniRoute-Progress` | Vastaus | `enabled` jos edistymisen seuranta on | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Upotukset +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Saatavilla olevat toimittajat: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Kuvan luominen +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Saatavilla olevat toimittajat: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Listaa mallit +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Yhteensopivuuden päätepisteet +## Compatibility Endpoints -| Menetelmä | Polku | Muoto | -| --------- | --------------------------- | ---------------------------- | -| POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Antrooppinen | -| POST | `/v1/responses` | OpenAI-vastaukset | -| POST | `/v1/embeddings` | OpenAI | -| POST | `/v1/images/generations` | OpenAI | -| HANKI | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Antrooppinen | -| HANKI | `/v1beta/models` | Kaksoset | -| POST | `/v1beta/models/{...path}` | Kaksoset generoivat sisältöä | -| POST | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Palveluntarjoajan reitit +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Palveluntarjoajan etuliite lisätään automaattisesti, jos se puuttuu. Yhteensopimattomat mallit palauttavat `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Semanttinen välimuisti +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Vastausesimerkki: +Response example: ```json { @@ -162,154 +162,164 @@ Vastausesimerkki: --- -## Kojelauta ja hallinta +## Dashboard & Management -### Todennus +### Authentication -| Päätepiste | Menetelmä | Kuvaus | -| ----------------------------- | --------- | ------------------------------------ | -| `/api/auth/login` | POST | Kirjaudu | -| `/api/auth/logout` | POST | Kirjaudu ulos | -| `/api/settings/require-login` | GET/PUT | Vaihda sisäänkirjautuminen vaaditaan | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Palveluntarjoajan hallinta +### Provider Management -| Päätepiste | Menetelmä | Kuvaus | -| ---------------------------- | ------------------- | ---------------------------------------- | -| `/api/providers` | HANKI/LÄHETÄ | Luettelo / luo palveluntarjoajat | -| `/api/providers/[id]` | GET/PUT/DELETE | Hallinnoi palveluntarjoajaa | -| `/api/providers/[id]/test` | POST | Testaa palveluntarjoajan yhteyttä | -| `/api/providers/[id]/models` | HANKI | Luettelo tarjoajan mallit | -| `/api/providers/validate` | POST | Tarkista palveluntarjoajan konfiguraatio | -| `/api/provider-nodes*` | Erilaisia ​​ | Palveluntarjoajan solmuhallinta | -| `/api/provider-models` | HANKI/LÄHETÄ/POISTA | Räätälöidyt mallit | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth-kulkuja +### OAuth Flows -| Päätepiste | Menetelmä | Kuvaus | -| -------------------------------- | ------------ | ------------------------------- | -| `/api/oauth/[provider]/[action]` | Erilaisia ​​ | Palveluntarjoajakohtainen OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Reititys ja konfigurointi +### Routing & Config -| Päätepiste | Menetelmä | Kuvaus | -| --------------------- | ------------ | ----------------------------------------- | -| `/api/models/alias` | HANKI/LÄHETÄ | Mallialiakset | -| `/api/models/catalog` | HANKI | Kaikki mallit toimittajan + tyypin mukaan | -| `/api/combos*` | Erilaisia ​​ | Yhdistelmähallinta | -| `/api/keys*` | Erilaisia ​​ | API-avainten hallinta | -| `/api/pricing` | HANKI | Mallin hinnoittelu | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Käyttö ja analyysi +### Usage & Analytics -| Päätepiste | Menetelmä | Kuvaus | -| --------------------------- | --------- | ---------------------- | -| `/api/usage/history` | HANKI | Käyttöhistoria | -| `/api/usage/logs` | HANKI | Käyttölokit | -| `/api/usage/request-logs` | HANKI | Pyyntötason lokit | -| `/api/usage/[connectionId]` | HANKI | Yhteyskohtainen käyttö | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Asetukset +### Settings -| Päätepiste | Menetelmä | Kuvaus | -| ------------------------------- | --------- | ---------------------------------- | -| `/api/settings` | GET/PUT | Yleiset asetukset | -| `/api/settings/proxy` | GET/PUT | Verkon välityspalvelimen asetukset | -| `/api/settings/proxy/test` | POST | Testaa välityspalvelinyhteyttä | -| `/api/settings/ip-filter` | GET/PUT | IP-sallitut/estolistat | -| `/api/settings/thinking-budget` | GET/PUT | Perustelujen merkkibudjetti | -| `/api/settings/system-prompt` | GET/PUT | Globaali järjestelmäkehote | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Valvonta +### Monitoring -| Päätepiste | Menetelmä | Kuvaus | -| ------------------------ | ------------ | ----------------------------- | -| `/api/sessions` | HANKI | Aktiivinen istunnon seuranta | -| `/api/rate-limits` | HANKI | Tilikohtaiset korkorajat | -| `/api/monitoring/health` | HANKI | Terveystarkastus | -| `/api/cache` | HANKI/POISTA | Välimuistitilastot / tyhjennä | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Varmuuskopiointi ja vienti/tuonti +### Backup & Export/Import -| Päätepiste | Menetelmä | Kuvaus | -| --------------------------- | --------- | ------------------------------------------------ | -| `/api/db-backups` | HANKI | Luettelo käytettävissä olevista varmuuskopioista | -| `/api/db-backups` | PUT | Luo manuaalinen varmuuskopio | -| `/api/db-backups` | POST | Palauta tietystä varmuuskopiosta | -| `/api/db-backups/export` | HANKI | Lataa tietokanta .sqlite-tiedostona | -| `/api/db-backups/import` | POST | Lataa .sqlite-tiedosto korvataksesi tietokannan | -| `/api/db-backups/exportAll` | HANKI | Lataa koko varmuuskopio .tar.gz-arkistona | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | ### Cloud Sync -| Päätepiste | Menetelmä | Kuvaus | -| ---------------------- | ------------ | -------------------------- | -| `/api/sync/cloud` | Erilaisia ​​ | Pilvisynkronointitoiminnot | -| `/api/sync/initialize` | POST | Alusta synkronointi | -| `/api/cloud/*` | Erilaisia ​​ | Pilvihallinta | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI-työkalut +### CLI Tools -| Päätepiste | Menetelmä | Kuvaus | -| ---------------------------------- | --------- | ------------------- | -| `/api/cli-tools/claude-settings` | HANKI | Claude CLI tila | -| `/api/cli-tools/codex-settings` | HANKI | Codex CLI -tila | -| `/api/cli-tools/droid-settings` | HANKI | Droidin CLI-tila | -| `/api/cli-tools/openclaw-settings` | HANKI | OpenClaw CLI tila | -| `/api/cli-tools/runtime/[toolId]` | HANKI | Yleinen CLI-ajoaika | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -CLI-vastauksia ovat: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). ### Resilience & Rate Limits -| Päätepiste | Menetelmä | Kuvaus | -| ----------------------- | --------- | --------------------------------- | -| `/api/resilience` | GET/PUT | Hanki/päivitä joustavuusprofiilit | -| `/api/resilience/reset` | POST | Nollaa katkaisijat | -| `/api/rate-limits` | HANKI | Tilikohtaisen koron rajan tila | -| `/api/rate-limit` | HANKI | Yleisen nopeusrajan määritys | +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | ### Evals -| Päätepiste | Menetelmä | Kuvaus | -| ------------ | ------------ | --------------------------------------- | -| `/api/evals` | HANKI/LÄHETÄ | Listaa eval-sviitit / suorita arviointi | +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -### Käytännöt +### Policies -| Päätepiste | Menetelmä | Kuvaus | -| --------------- | ------------------- | --------------------------- | -| `/api/policies` | HANKI/LÄHETÄ/POISTA | Hallitse reitityskäytäntöjä | +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -### Vaatimustenmukaisuus +### Compliance -| Päätepiste | Menetelmä | Kuvaus | -| --------------------------- | --------- | -------------------------------------------------- | -| `/api/compliance/audit-log` | HANKI | Vaatimustenmukaisuuden tarkastusloki (viimeinen N) | +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### v1beta (Gemini-yhteensopiva) +### v1beta (Gemini-Compatible) -| Päätepiste | Menetelmä | Kuvaus | -| -------------------------- | --------- | ----------------------------------- | -| `/v1beta/models` | HANKI | Listaa mallit Gemini-muodossa | -| `/v1beta/models/{...path}` | POST | Gemini `generateContent` päätepiste | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -Nämä päätepisteet heijastavat Geminin API-muotoa asiakkaille, jotka odottavat natiivi Gemini SDK -yhteensopivuutta. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. -### Sisäiset / järjestelmäsovellusliittymät +### Internal / System APIs -| Päätepiste | Menetelmä | Kuvaus | -| --------------- | --------- | ------------------------------------------------------------------ | -| `/api/init` | HANKI | Sovelluksen alustuksen tarkistus (käytetty ensimmäisellä kerralla) | -| `/api/tags` | HANKI | Ollama-yhteensopivat mallitunnisteet (Ollama-asiakkaille) | -| `/api/restart` | POST | Käynnistä siro palvelimen uudelleenkäynnistys | -| `/api/shutdown` | POST | Laukaise siro palvelimen sammutus | +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | -> **Huomaa:** Näitä päätepisteitä käytetään sisäisesti järjestelmässä tai Ollama-asiakasyhteensopivuuden vuoksi. Loppukäyttäjät eivät yleensä soita niihin. +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Äänen transkriptio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Literoi äänitiedostot Deepgramilla tai AssemblyAI:lla. +Transcribe audio files using Deepgram or AssemblyAI. -**Pyyntö:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Vastaus:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Tuetut palveluntarjoajat:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Tuetut muodot:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Ollama-yhteensopivuus +## Ollama Compatibility -Asiakkaille, jotka käyttävät Ollaman API-muotoa: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Pyynnöt käännetään automaattisesti Ollaman ja sisäisten muotojen välillä. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetria +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Vastaus:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Budjetti +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Mallin saatavuus +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Pyynnön käsittely +## Request Processing -1. Asiakas lähettää pyynnön osoitteeseen `/v1/*` -2. Reitinkäsittelijän kutsut `handleChat`, `handleEmbedding`, `handleAudioTranscription` tai `handleImageGeneration` -3. Malli on ratkaistu (suora toimittaja/malli tai alias/yhdistelmä) -4. Tunnustiedot on valittu paikallisesta tietokannasta tilin saatavuussuodatuksella -5. Chat: `handleChatCore` — muodon tunnistus, käännös, välimuistin tarkistus, idempotenssin tarkistus -6. Palveluntarjoajan toteuttaja lähettää alkupään pyynnön -7. Vastaus käännetty takaisin asiakasmuotoon (chat) tai palautettu sellaisenaan (upotukset/kuvat/ääni) -8. Käyttö/loki kirjattu -9. Varmennus koskee virheitä yhdistelmäsääntöjen mukaisesti +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Koko arkkitehtuuriviite: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Todennus +## Authentication -- Hallintapaneelireitit (`/dashboard/*`) käyttävät `auth_token` evästettä -- Kirjautuminen käyttää tallennettua salasanahajautusta; varaa `INITIAL_PASSWORD` -- `requireLogin` vaihdettavissa kautta `/api/settings/require-login` -- `/v1/*` reitit vaativat valinnaisesti Bearer API -avaimen, kun `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/fi/ARCHITECTURE.md b/docs/i18n/fi/ARCHITECTURE.md index f1f4ff6525..258d62df53 100644 --- a/docs/i18n/fi/ARCHITECTURE.md +++ b/docs/i18n/fi/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# OmniRoute-arkkitehtuuri +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Viimeksi päivitetty: 2026-02-18_ +_Last updated: 2026-03-04_ -## Tiivistelmä +## Executive Summary -OmniRoute on paikallinen AI-reititysyhdyskäytävä ja kojelauta, joka on rakennettu Next.js:lle. -Se tarjoaa yhden OpenAI-yhteensopivan päätepisteen (`/v1/*`) ja reitittää liikenteen useiden alkupään palveluntarjoajien kesken kääntämisen, varaosion, tunnuksen päivityksen ja käytön seurannan avulla. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Ydinominaisuudet: +Core capabilities: -- OpenAI-yhteensopiva API-pinta CLI:lle/työkaluille (28 toimittajaa) -- Pyydä/vastaa käännös palveluntarjoajan eri formaattien välillä -- Mallin yhdistelmävara (usean mallin sarja) -- Tilitason varatoiminto (usea tili palveluntarjoajaa kohti) -- OAuth + API-avain tarjoajan yhteyden hallinta -- Upotus sukupolvi `/v1/embeddings`:n kautta (6 toimittajaa, 9 mallia) -- Kuvien luominen `/v1/images/generations`:n kautta (4 toimittajaa, 9 mallia) -- Ajattele tagien jäsentämistä (`...`) päättelymalleille -- Vastauksen desinfiointi tiukan OpenAI SDK -yhteensopivuuden takaamiseksi -- Roolien normalisointi (kehittäjä→järjestelmä, järjestelmä→käyttäjä) palveluntarjoajien välistä yhteensopivuutta varten -- Strukturoitu lähdön muunnos (json_schema → Gemini responseSchema) -- Paikallinen pysyvyys tarjoajille, avaimille, aliaksille, yhdistelmille, asetuksille, hinnoittelulle -- Käytön/kustannusten seuranta ja pyyntöjen kirjaaminen -- Valinnainen pilvisynkronointi usean laitteen/tilan synkronointiin -- IP-sallitut / estolistat API-käyttöoikeuksien hallinnassa -- Ajatteleva budjetin hallinta (passthrough/auto/mukautettu/adaptiivinen) -- Globaali järjestelmän nopea ruiskutus -- Istunnon seuranta ja sormenjäljet -- Tilikohtainen tehostettu hintarajoitus tarjoajakohtaisilla profiileilla -- Katkaisijakuvio palveluntarjoajan joustavuuden parantamiseksi -- Ukkosta estävä laumasuoja mutex-lukolla -- Allekirjoituspohjainen pyyntöjen duplikoinnin välimuisti -- Verkkotunnustaso: mallin saatavuus, hintasäännöt, varakäytäntö, lukituskäytäntö -- Verkkotunnuksen tilan pysyvyys (SQLite-kirjoitusvälimuisti varauksille, budjeteille, lukituksille, katkaisimille) -- Käytäntömoottori keskitettyä pyyntöjen arviointia varten (sulku → budjetti → vara) -- Pyydä telemetriaa p50/p95/p99-latenssiaggregaatiolla -- Korrelaatiotunnus (X-Request-Id) päästä päähän -jäljitykseen -- Vaatimustenmukaisuuden tarkastuksen kirjaaminen ja opt-out API-avaimella -- Eval-kehys LLM-laadunvarmistukseen -- Joustavan käyttöliittymän kojelauta, jossa on reaaliaikainen katkaisijatila -- Modulaariset OAuth-palveluntarjoajat (12 yksittäistä moduulia alla `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Ensisijainen suoritusaikamalli: +Primary runtime model: -- Next.js-sovellusreitit `src/app/api/*` -sovelluksessa toteuttavat sekä hallintapaneelin sovellusliittymiä että yhteensopivuussovellusliittymiä -- Jaettu SSE/reititysydin kohteissa `src/sse/*` + `open-sse/*` hoitaa palveluntarjoajan suorittamisen, käännöksen, suoratoiston, varatoiminnon ja käytön +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Laajuus ja rajat +## Scope and Boundaries -### Soveltamisalalla +### In Scope -- Paikallisen yhdyskäytävän suoritusaika -- Kojelaudan hallintasovellusliittymät -- Palveluntarjoajan todennus ja tunnuksen päivitys -- Pyydä käännöstä ja SSE-suoratoistoa -- Paikallinen tila + käytön pysyvyys -- Valinnainen pilvisynkronointiorkesteri +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Soveltamisalan ulkopuolella +### Out of Scope -- Pilvipalvelun toteutus `NEXT_PUBLIC_CLOUD_URL`:n takana -- Palveluntarjoajan SLA/ohjaustaso paikallisen prosessin ulkopuolella -- Itse ulkoiset CLI-binaarit (Claude CLI, Codex CLI jne.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Korkean tason järjestelmäkonteksti +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Suorituksenaikaiset ydinkomponentit +## Core Runtime Components -## 1) API ja reitityskerros (Next.js App Routes) +## 1) API and Routing Layer (Next.js App Routes) -Päähakemistot: +Main directories: -- `src/app/api/v1/*` ja `src/app/api/v1beta/*` yhteensopiville sovellusliittymille -- `src/app/api/*` hallinta-/määrityssovellusliittymille -- Seuraavaksi kirjoitetaan uudelleen `next.config.mjs` kartassa `/v1/*` arvoon `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Tärkeitä yhteensopivuusreittejä: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` - sisältää mukautettuja malleja, joissa on `custom: true` -- `src/app/api/v1/embeddings/route.ts` - upottaminen (6 palveluntarjoajaa) -- `src/app/api/v1/images/generations/route.ts` — kuvan luominen (4+ tarjoajaa, mukaan lukien Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` - palveluntarjoajakohtainen keskustelu -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` – omat palveluntarjoajakohtaiset upotukset -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` – palveluntarjoajakohtaiset kuvat +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Hallintoverkkotunnukset: +Management domains: -- Todennus/asetukset: `src/app/api/auth/*`, `src/app/api/settings/*` -- Palveluntarjoajat/yhteydet: `src/app/api/providers*` -- Palveluntarjoajan solmut: `src/app/api/provider-nodes*` -- Mukautetut mallit: `src/app/api/provider-models` (GET/POST/DELETE) -- Malliluettelo: `src/app/api/models/catalog` (GET) -- Välityspalvelimen kokoonpano: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Avaimet/aliakset/kombot/hinnoittelu: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Käyttö: `src/app/api/usage/*` -- Synkronointi/pilvi: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI-työkalujen avustajat: `src/app/api/cli-tools/*` -- IP-suodatin: `src/app/api/settings/ip-filter` (GET/PUT) -- Arvioitu budjetti: `src/app/api/settings/thinking-budget` (GET/PUT) -- Järjestelmäkehote: `src/app/api/settings/system-prompt` (GET/PUT) -- Istunnot: `src/app/api/sessions` (GET) -- Hintarajoitukset: `src/app/api/rate-limits` (GET) -- Joustavuus: `src/app/api/resilience` (GET/PATCH) – palveluntarjoajan profiilit, katkaisija, nopeusrajoitustila -- Kestävyyden nollaus: `src/app/api/resilience/reset` (POST) - nollaa katkaisijat + jäähdytys -- Välimuistitilastot: `src/app/api/cache/stats` (GET/DELETE) -- Mallin saatavuus: `src/app/api/models/availability` (GET/POST) -- Telemetria: `src/app/api/telemetry/summary` (GET) -- Budjetti: `src/app/api/usage/budget` (GET/POST) -- Varaketjut: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Vaatimustenmukaisuustarkastus: `src/app/api/compliance/audit-log` (GET) -- Arvot: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Käytännöt: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Käännösydin +## 2) SSE + Translation Core -Päävirtausmoduulit: +Main flow modules: -- Merkintä: `src/sse/handlers/chat.ts` -- Ydinorkesteri: `open-sse/handlers/chatCore.ts` -- Palveluntarjoajan suoritussovittimet: `open-sse/executors/*` -- Muototunnistuksen/palveluntarjoajan määritykset: `open-sse/services/provider.ts` -- Mallin jäsennys/selvitys: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Tilin varalogiikka: `open-sse/services/accountFallback.ts` -- Käännösrekisteri: `open-sse/translator/index.ts` -- Suoratoistomuunnokset: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Käytön purkaminen/normalisointi: `open-sse/utils/usageTracking.ts` -- Think tag -jäsennin: `open-sse/utils/thinkTagParser.ts` -- Upotuskäsittelijä: `open-sse/handlers/embeddings.ts` -- Upotuspalveluntarjoajan rekisteri: `open-sse/config/embeddingRegistry.ts` -- Kuvanluontikäsittelijä: `open-sse/handlers/imageGeneration.ts` -- Kuvantarjoajan rekisteri: `open-sse/config/imageRegistry.ts` -- Vastauksen desinfiointi: `open-sse/handlers/responseSanitizer.ts` -- Roolin normalisointi: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Palvelut (liiketoimintalogiikka): +Services (business logic): -- Tilin valinta/pisteytys: `open-sse/services/accountSelector.ts` -- Kontekstin elinkaarihallinta: `open-sse/services/contextManager.ts` -- IP-suodattimen valvonta: `open-sse/services/ipFilter.ts` -- Istunnon seuranta: `open-sse/services/sessionManager.ts` -- Pyydä kopioiden poistoa: `open-sse/services/signatureCache.ts` -- Järjestelmäkehotteen lisäys: `open-sse/services/systemPrompt.ts` -- Ajatteleva budjetin hallinta: `open-sse/services/thinkingBudget.ts` -- Jokerimerkkimallin reititys: `open-sse/services/wildcardRouter.ts` -- Hintarajoitusten hallinta: `open-sse/services/rateLimitManager.ts` -- Katkaisija: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Domain-kerroksen moduulit: +Domain layer modules: -- Mallin saatavuus: `src/lib/domain/modelAvailability.ts` -- Kustannussäännöt/budjetit: `src/lib/domain/costRules.ts` -- Varakäytäntö: `src/lib/domain/fallbackPolicy.ts` -- Yhdistelmäratkaisu: `src/lib/domain/comboResolver.ts` -- Lukituskäytäntö: `src/lib/domain/lockoutPolicy.ts` -- Käytäntömoottori: `src/domain/policyEngine.ts` — keskitetty lukitus → budjetti → varaarviointi -- Virhekoodiluettelo: `src/lib/domain/errorCodes.ts` -- Pyynnön tunnus: `src/lib/domain/requestId.ts` -- Noudon aikakatkaisu: `src/lib/domain/fetchTimeout.ts` -- Pyydä telemetriaa: `src/lib/domain/requestTelemetry.ts` -- Vaatimustenmukaisuus/tarkastus: `src/lib/domain/compliance/index.ts` -- Eval juoksija: `src/lib/domain/evalRunner.ts` -- Verkkotunnuksen tilan pysyvyys: `src/lib/db/domainState.ts` — SQLite CRUD varaketjuille, budjeteille, kustannushistorialle, lukitustilalle, katkaisimille +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth-palveluntarjoajan moduulit (12 yksittäistä tiedostoa kohdassa `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Rekisterihakemisto: `src/lib/oauth/providers/index.ts` -- Yksittäiset palveluntarjoajat: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, ,\_1 `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Ohut kääre: `src/lib/oauth/providers.ts` - jälleenvienti yksittäisistä moduuleista +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Pysyvyyskerros +## 3) Persistence Layer -Ensisijainen tila DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- tiedosto: `${DATA_DIR}/db.json` (tai `$XDG_CONFIG_HOME/omniroute/db.json`, kun se on asetettu, muuten `~/.omniroute/db.json`) -- entiteetit: providerConnections, providerNodes, mallialiakset, yhdistelmät, apiKeys, asetukset, hinnoittelu, **customModels**, **proxyConfig**, **ipFilter**, **thhinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -DB:n käyttö: +Usage persistence: -- `src/lib/usageDb.ts` -- tiedostot: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- noudattaa samaa perushakemistokäytäntöä kuin `localDb` (`DATA_DIR`, sitten `XDG_CONFIG_HOME/omniroute`, kun se on asetettu) -- jaettu kohdistetuiksi alamoduuleiksi: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present Domain State DB (SQLite): -- `src/lib/db/domainState.ts` - CRUD-toiminnot toimialueen tilassa -- Taulukot (luotu `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, -- Kirjoitusvälimuistin malli: muistissa olevat kartat ovat arvovaltaisia ajon aikana; mutaatiot kirjoitetaan synkronisesti SQLiten kanssa; tila palautetaan DB:stä kylmäkäynnistyksen yhteydessä +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start ## 4) Auth + Security Surfaces -- Hallintapaneelin evästeiden todennus: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- API-avaimen luominen/vahvistus: `src/shared/utils/apiKey.ts` -- Palveluntarjoajan salaisuudet säilyivät `providerConnections` tiedoissa -- Lähtevän välityspalvelimen tuki `open-sse/utils/proxyFetch.ts` (env vars) ja `open-sse/utils/networkProxy.ts` (määritettävä palveluntarjoajakohtaisesti tai globaali) kautta +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) ## 5) Cloud Sync -- Aikataulun aloitus: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Säännöllinen tehtävä: `src/shared/services/cloudSyncScheduler.ts` -- Ohjausreitti: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Pyynnön elinkaari (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Yhdistelmä + tilin varavirta +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Varapäätökset tehdään `open-sse/services/accountFallback.ts`:n avulla tilakoodeja ja virheviestiheuristiikkaa käyttämällä. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuthin käyttöönotto ja tunnuksen päivityksen elinkaari +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Päivitys reaaliaikaisen liikenteen aikana suoritetaan `open-sse/handlers/chatCore.ts` -suorittimen `refreshCredentials()` sisällä. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Cloud Sync -elinkaari (Ota käyttöön / Synkronoi / Poista käytöstä) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Jaksottaisen synkronoinnin käynnistää `CloudSyncScheduler`, kun pilvi on käytössä. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Tietomalli ja tallennuskartta +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Fyysiset tallennustiedostot: +Physical storage files: -- päätila: `${DATA_DIR}/db.json` (tai `$XDG_CONFIG_HOME/omniroute/db.json`, kun se on asetettu, muuten `~/.omniroute/db.json`) -- käyttötilastot: `${DATA_DIR}/usage.json` -- pyyntölokin rivit: `${DATA_DIR}/log.txt` -- valinnainen kääntäjä/pyydä virheenkorjausistuntoja: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Käyttöönoton topologia +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Moduulikartoitus (päätöskriittinen) +## Module Mapping (Decision-Critical) -### Reitti- ja API-moduulit +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: yhteensopivuussovellusliittymät -- `src/app/api/v1/providers/[provider]/*`: omat palveluntarjoajakohtaiset reitit (chat, upotukset, kuvat) -- `src/app/api/providers*`: palveluntarjoajan CRUD, validointi, testaus -- `src/app/api/provider-nodes*`: mukautettu yhteensopiva solmuhallinta -- `src/app/api/provider-models`: mukautetun mallin hallinta (CRUD) -- `src/app/api/models/catalog`: täydellinen malliluettelosovellusliittymä (kaikki tyypit ryhmitelty tarjoajan mukaan) -- `src/app/api/oauth/*`: OAuth-/laitekoodivirrat -- `src/app/api/keys*`: paikallisen API-avaimen elinkaari -- `src/app/api/models/alias`: aliaksen hallinta -- `src/app/api/combos*`: varayhdistelmähallinta -- `src/app/api/pricing`: hinnoittelun ohitukset kustannuslaskennassa -- `src/app/api/settings/proxy`: välityspalvelimen määritys (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: lähtevän välityspalvelimen yhteystesti (POST) -- `src/app/api/usage/*`: käyttö- ja lokisovellusliittymät -- `src/app/api/sync/*` + `src/app/api/cloud/*`: pilvisynkronointi ja pilveen suuntautuvat apulaiset -- `src/app/api/cli-tools/*`: paikalliset CLI-asetusten kirjoittajat/tarkistajat -- `src/app/api/settings/ip-filter`: IP-sallittu/estolista (GET/PUT) -- `src/app/api/settings/thinking-budget`: ajattelutunnuksen budjettimääritys (GET/PUT) -- `src/app/api/settings/system-prompt`: yleinen järjestelmäkehote (GET/PUT) -- `src/app/api/sessions`: aktiivisen istunnon luettelo (GET) -- `src/app/api/rate-limits`: tilikohtainen korkorajoitustila (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Reititys- ja suoritusydin +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: pyynnön jäsennys, yhdistelmäkäsittely, tilin valintasilmukka -- `open-sse/handlers/chatCore.ts`: käännös, suorittajan lähettäminen, uudelleenyritysten/päivitysten käsittely, streamin määritys -- `open-sse/executors/*`: palveluntarjoajakohtainen verkko- ja muotokäyttäytyminen +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Käännösrekisteri ja muotomuuntimet +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: kääntäjän rekisteri ja orkestrointi -- Pyydä kääntäjiä: `open-sse/translator/request/*` -- Vastausten kääntäjät: `open-sse/translator/response/*` -- Muotovakiot: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Pysyvyys +### Persistence -- `src/lib/localDb.ts`: pysyvä kokoonpano/tila -- `src/lib/usageDb.ts`: käyttöhistoria ja rullaavat pyyntölokit +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Palveluntarjoajan kattavuus (strategiamalli) +## Provider Executor Coverage (Strategy Pattern) -Jokaisella palveluntarjoajalla on erikoistunut suorittaja, joka laajentaa `BaseExecutor` (kohdassa `open-sse/executors/base.ts`), joka tarjoaa URL-osoitteen rakentamisen, otsikon rakentamisen, uudelleenyrityksen eksponentiaalisella perääntymisellä, valtuustietojen päivityskoukut ja `execute()`-orkesterimenetelmän. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Toteuttaja | Palveluntarjoaja(t) | Erikoiskäsittely | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, ilotulitus, Cerebras, Cohere, NVIDIA | Dynaaminen URL-/otsikkomääritykset tarjoajakohtaisesti | -| `AntigravityExecutor` | Google Antigravity | Mukautetut projekti-/istuntotunnukset, Yritä uudelleen jäsentämisen jälkeen | -| `CodexExecutor` | OpenAI Codex | Syöttää järjestelmäohjeita, pakottaa päättelyponnistuksen | -| `CursorExecutor` | Kohdistin IDE | ConnectRPC-protokolla, Protobuf-koodaus, pyynnön allekirjoitus tarkistussumman kautta | -| `GithubExecutor` | GitHub Copilot | Copilot-tunnuksen päivitys, VSC-koodia jäljittelevät otsikot | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binaarimuoto → SSE-muunnos | -| `GeminiCLIExecutor` | Gemini CLI | Google OAuth -tunnuksen päivitysjakso | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Kaikki muut palveluntarjoajat (mukaan lukien mukautetut yhteensopivat solmut) käyttävät `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Tarjoajan yhteensopivuusmatriisi +## Provider Compatibility Matrix -| Palveluntarjoaja | Muoto | Auth | Striimaa | Ei-stream | Token Refresh | Käyttösovellusliittymä | -| ---------------- | ----------------- | ------------------------- | -------------------- | --------- | ------------- | --------------------------- | -| Claude | claude | API-avain / OAuth | ✅ | ✅ | ✅ | ⚠️ Vain järjestelmänvalvoja | -| Kaksoset | kaksoset | API-avain / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Antigravitaatio | antigravitaatio | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | -| OpenAI | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-vastaukset | OAuth | ✅ pakotettu | ❌ | ✅ | ✅ Hintarajat | -| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Kiintiön tilannekuvat | -| Kursori | kohdistin | Mukautettu tarkistussumma | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (TapahtumaStream) | ❌ | ✅ | ✅ Käyttörajoitukset | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Pyynnöstä | -| iFlow | openai | OAuth (Perus) | ✅ | ✅ | ✅ | ⚠️ Pyynnöstä | -| OpenRouter | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | API-avain | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| Hämmennys | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| Yhdessä AI | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| Ilotulitus AI | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| Aivot | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| Cohere | openai | API-avain | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API-avain | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Käännösten muoto +## Format Translation Coverage -Havaittuja lähdemuotoja ovat: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Kohdemuotoja ovat: +Target formats include: -- OpenAI chat / vastaukset +- OpenAI chat/Responses - Claude -- Gemini/Gemini-CLI/Antigravity-kuori +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Kursori +- Cursor -Käännöksissä käytetään keskitinmuotona **OpenAI-muotoa** — kaikki konversiot menevät OpenAI:n kautta välimuotona: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Käännökset valitaan dynaamisesti lähteen hyötykuorman muodon ja toimittajan kohdemuodon perusteella. +Translations are selected dynamically based on source payload shape and provider target format. -Muut käsittelytasot käännösputkessa: +Additional processing layers in the translation pipeline: -- **Vastausten puhdistaminen** – Poistaa standardista poikkeavat kentät OpenAI-muotoisista vastauksista (sekä suoratoistosta että ei-suoratoistosta) varmistaakseen tiukan SDK-yhteensopivuuden -- **Roolin normalisointi** — Muuntaa `developer` → `system` muille kuin OpenAI-kohteille; yhdistää `system` → `user` malleille, jotka hylkäävät järjestelmäroolin (GLM, ERNIE) -- **Ajattele tunnisteen purkamista** — jäsentää `...` lohkoa sisällöstä kenttään `reasoning_content` -- **Strukturoitu tulos** — Muuntaa OpenAI `response_format.json_schema` Geminin `responseMimeType` + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Tuetut API-päätepisteet +## Supported API Endpoints -| Päätepiste | Muoto | Käsittelijä | -| -------------------------------------------------- | ---------------------------- | ----------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Viestit | Sama käsittelijä (tunnistettu automaattisesti) | -| `POST /v1/responses` | OpenAI-vastaukset | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Malliluettelo | API reitti | -| `POST /v1/images/generations` | OpenAI-kuvat | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Malliluettelo | API reitti | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Palveluntarjoajakohtainen mallin validointi | -| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Palveluntarjoajakohtainen mallin validointi | -| `POST /v1/providers/{provider}/images/generations` | OpenAI-kuvat | Palveluntarjoajakohtainen mallin validointi | -| `POST /v1/messages/count_tokens` | Claude Token Count | API reitti | -| `GET /v1/models` | OpenAI-mallien luettelo | API-reitti (chat + upotus + kuva + mukautetut mallit) | -| `GET /api/models/catalog` | Luettelo | Kaikki mallit ryhmitelty tarjoajan + tyypin mukaan | -| `POST /v1beta/models/*:streamGenerateContent` | Gemini syntyperäinen | API reitti | -| `GET/PUT/DELETE /api/settings/proxy` | Välityspalvelimen kokoonpano | Verkon välityspalvelimen määritykset | -| `POST /api/settings/proxy/test` | Välityspalvelinyhteydet | Välityspalvelimen kunto/yhteystestin päätepiste | -| `GET/POST/DELETE /api/provider-models` | Mukautetut mallit | Mukautetun mallin hallinta toimittajaa kohden | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Ohituskäsittelijä +## Bypass Handler -Ohituskäsittelijä (`open-sse/utils/bypassHandler.ts`) sieppaa Claude CLI:n tunnetut "poistopyynnöt" – lämmittelypingit, otsikon poiminnot ja tunnukset - ja palauttaa **väärennetyn vastauksen** kuluttamatta ylävirran toimittajatunnuksia. Tämä käynnistyy vain, kun `User-Agent` sisältää `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Pyydä Logger Pipeline +## Request Logger Pipeline -Pyyntöloggeri (`open-sse/utils/requestLogger.ts`) tarjoaa 7-vaiheisen virheenkorjauslokiputken, joka on oletuksena poistettu käytöstä ja otettu käyttöön `ENABLE_REQUEST_LOGS=true`:n kautta: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Tiedostot kirjoitetaan osoitteeseen `/logs//` jokaista pyyntöistuntoa varten. +Files are written to `/logs//` for each request session. -## Vikatilat ja joustavuus +## Failure Modes and Resilience -## 1) Tilin/palveluntarjoajan saatavuus +## 1) Account/Provider Availability -- Palveluntarjoajan tilin jäähtyminen ohimenevien / nopeus / todennusvirheiden vuoksi -- tilin varaosa ennen epäonnistunutta pyyntöä -- Yhdistelmämallin palautus, kun nykyisen mallin/palveluntarjoajan polku on käytetty loppuun +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Tokenin vanheneminen +## 2) Token Expiry -- esitarkista ja päivitä yrittämällä uudelleen päivitettävien palveluntarjoajien kohdalla -- 401/403 yritä uudelleen päivitysyrityksen jälkeen ydinpolulla +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path ## 3) Stream Safety -- irrotettava stream-ohjain -- käännösvirta streamin lopun huuhtelemalla ja `[DONE]` käsittelyllä -- käyttöarvion varavaihtoehto, kun palveluntarjoajan käytön metatiedot puuttuvat +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Pilvisynkronoinnin heikkeneminen +## 4) Cloud Sync Degradation -- Synkronointivirheet tulevat esiin, mutta paikallinen suoritusaika jatkuu -- ajastimessa on uudelleenyrityslogiikka, mutta säännöllinen suoritus tällä hetkellä kutsuu oletusarvoisesti yhden yrityksen synkronointia +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Tietojen eheys +## 5) Data Integrity -- DB-muodon siirto/korjaus puuttuviin avaimiin -- Vioittuneet JSON-nollaussuojat localDb:lle ja usageDb:lle +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Havaittavuus ja toimintasignaalit +## Observability and Operational Signals -Ajonaikaisen näkyvyyden lähteet: +Runtime visibility sources: -- konsolin lokit lähteestä `src/sse/utils/logger.ts` -- pyyntökohtaiset käyttöaggregaatit kohteessa `usage.json` -- tekstimuotoisen pyynnön tilakirjautuminen `log.txt` -- valinnaiset syväpyyntö-/käännöslokit kohdassa `logs/`, kun `ENABLE_REQUEST_LOGS=true` -- hallintapaneelin käytön päätepisteet (`/api/usage/*`) käyttöliittymän käyttöä varten +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Turvallisuusherkät rajat +## Security-Sensitive Boundaries -- JWT-salaisuus (`JWT_SECRET`) suojaa hallintapaneelin istunnon evästeen vahvistuksen/allekirjoituksen -- Alkuperäinen salasana (`INITIAL_PASSWORD`, oletus `123456`) on ohitettava todellisissa käyttöönotoissa -- API-avaimen HMAC-salaisuus (`API_KEY_SECRET`) suojaa luodun paikallisen API-avainmuodon -- Tarjoajan salaisuudet (API-avaimet/tunnisteet) säilyvät paikallisessa tietokannassa, ja ne tulee suojata tiedostojärjestelmätasolla -- Pilvisynkronoinnin päätepisteet perustuvat API-avaimen todennus + konetunnuksen semantiikkaan +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Ympäristö ja suoritusaikamatriisi +## Environment and Runtime Matrix -Koodin aktiivisesti käyttämät ympäristömuuttujat: +Environment variables actively used by code: -- Sovellus/todennus: `JWT_SECRET`, `INITIAL_PASSWORD` -- Tallennustila: `DATA_DIR` -- Yhteensopivan solmun käyttäytyminen: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Valinnainen tallennuspohjan ohitus (Linux/macOS, kun `DATA_DIR` ei ole asetettu): `XDG_CONFIG_HOME` -- Suojaustiivistys: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Kirjautuminen: `ENABLE_REQUEST_LOGS` -- Synkronointi/pilvi-URL-osoite: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Lähtevä välityspalvelin: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` ja pienillä kirjaimilla kirjoitetut versiot -- SOCKS5-ominaisuusliput: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Alusta/ajonaikaiset apuohjelmat (ei sovelluskohtaiset asetukset): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Tunnettuja arkkitehtonisia huomautuksia +## Known Architectural Notes -1. `usageDb` ja `localDb` jakavat nyt saman perushakemistokäytännön (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) vanhan tiedoston siirron kanssa. -2. `/api/v1/route.ts` palauttaa staattisen malliluettelon, eikä se ole `/v1/models`:n käyttämä päämallien lähde. -3. Pyyntöloggeri kirjoittaa täydet otsikot/runko, kun se on käytössä; käsittele lokihakemistoa arkaluontoisena. -4. Pilven toiminta riippuu oikeasta `NEXT_PUBLIC_BASE_URL`- ja pilvipäätepisteen saavutettavuudesta. -5. Hakemisto `open-sse/` julkaistaan ​​`@omniroute/open-sse` **npm-työtilapaketina**. Lähdekoodi tuo sen `@omniroute/open-sse/...`:n kautta (ratkaisi Next.js `transpilePackages`). Tämän asiakirjan tiedostopolut käyttävät edelleen hakemistonimeä `open-sse/` johdonmukaisuuden vuoksi. -6. Hallintapaneelin kaaviot käyttävät **Uudelleenkaavioita** (SVG-pohjainen) helppokäyttöisten, interaktiivisten analytiikkavisualisoinnit (mallien käyttöpalkkikaaviot, toimittajien erittelytaulukot onnistumisprosentteineen) varten. -7. E2E-testeissä käytetään **Playwrightia** (`tests/e2e/`), suoritetaan `npm run test:e2e`:n kautta. Yksikkötesteissä käytetään **Node.js-testirunneria** (`tests/unit/`), suoritetaan `npm run test:plan3`:n kautta. Lähdekoodi kohdassa `src/` on **TypeScript** (`.ts`/`.tsx`); `open-sse/`-työtila pysyy JavaScriptina (`.js`). -8. Asetukset-sivu on järjestetty viiteen välilehteen: Suojaus, Reititys (6 globaalia strategiaa: täytä ensin, round-robin, p2c, satunnainen, vähiten käytetty, kustannusoptimoitu), Resilience (muokattavat nopeusrajoitukset, katkaisija, käytännöt), AI (ajattelubudjetti, järjestelmäkehote, kehote välimuisti), Advanced (välityspalvelin). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Toimintavarmennusten tarkistuslista +## Operational Verification Checklist -- Koonti lähteestä: `npm run build` -- Rakenna Docker-kuva: `docker build -t omniroute .` -- Aloita huolto ja varmista: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- CLI-kohteen perus-URL-osoitteen tulee olla `http://:20128/v1`, kun `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/fi/CODEBASE_DOCUMENTATION.md b/docs/i18n/fi/CODEBASE_DOCUMENTATION.md index 99ce2313ef..303880c198 100644 --- a/docs/i18n/fi/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/fi/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Codebase-dokumentaatio +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Kattava, aloittelijaystävällinen opas **omniroute** usean palveluntarjoajan AI-välityspalvelimen reitittimeen. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Mikä on omniroute? +## 1. What Is omniroute? -omniroute on **välityspalvelinreititin**, joka sijaitsee AI-asiakkaiden (Claude CLI, Codex, Cursor IDE jne.) ja tekoälypalvelujen tarjoajien (Anthropic, Google, OpenAI, AWS, GitHub jne.) välillä. Se ratkaisee yhden suuren ongelman: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Eri AI-asiakkaat puhuvat eri "kieliä" (API-muotoja), ja eri tekoälypalveluntarjoajat odottavat myös erilaisia "kieliä".** Omniroute kääntää niiden välillä automaattisesti. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Ajattele sitä kuin yleinen kääntäjä Yhdistyneissä Kansakunnissa – jokainen edustaja voi puhua mitä tahansa kieltä, ja kääntäjä muuntaa sen kenelle tahansa muulle edustajalle. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Arkkitehtuurin yleiskatsaus +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Keskeinen periaate: Keskittimen ja puheen käännös +### Core Principle: Hub-and-Spoke Translation -Kaikki muotojen käännökset kulkevat **OpenAI-muodon kautta keskittimenä**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Tämä tarkoittaa, että tarvitset vain **N kääntäjää** (yksi per muoto) **N²** (jokainen pari) sijaan. +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Projektin rakenne +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Erittely moduulilta +## 4. Module-by-Module Breakdown ### 4.1 Config (`open-sse/config/`) -**yksi totuuden lähde** kaikille palveluntarjoajan määrityksille. +The **single source of truth** for all provider configuration. -| Tiedosto | Tarkoitus | -| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS`-objekti, jossa on perus-URL-osoitteet, OAuth-tunnistetiedot (oletukset), otsikot ja oletusarvoiset järjestelmäkehotteet jokaiselle palveluntarjoajalle. Määrittää myös `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` ja `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Lataa ulkoiset valtuustiedot kohteesta `data/provider-credentials.json` ja yhdistää ne kovakoodattujen oletusarvojen päälle dokumentissa `PROVIDERS`. Pitää salaisuudet poissa lähteen hallinnasta säilyttäen samalla yhteensopivuuden taaksepäin. | -| `providerModels.ts` | Keskitetty mallirekisteri: karttatoimittajan aliakset → mallitunnukset. Toiminnot, kuten `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Codex-pyyntöihin lisätyt järjestelmäohjeet (muokkausrajoitukset, hiekkalaatikkosäännöt, hyväksymiskäytännöt). | -| `defaultThinkingSignature.ts` | Oletusarvoiset "ajattelevat" allekirjoitukset Claude- ja Gemini-malleille. | -| `ollamaModels.ts` | Kaaviomäärittely paikallisille Ollama-malleille (nimi, koko, perhe, kvantisointi). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Tunnistetietojen latausvirta +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Toimeenpanijat (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Toteuttajat kapseloivat **palveluntarjoajakohtaisen logiikan** käyttämällä **strategiamallia**. Jokainen suorittaja ohittaa perusmenetelmät tarpeen mukaan. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Toteuttaja | Palveluntarjoaja | Keskeiset erikoisalat | -| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Abstrakti pohja: URL-osoitteiden rakentaminen, otsikot, uudelleenyrityslogiikka, tunnistetietojen päivitys | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Yleinen OAuth-tunnuksen päivitys vakiopalveluntarjoajille | -| `antigravity.ts` | Google Cloud Code | Projektin/istunnon tunnuksen luominen, usean URL-osoitteen varaosa, mukautettu uudelleenjäsennysyritys virheilmoituksista ("reset after 2t7m23s") | -| `cursor.ts` | Kohdistin IDE | **Monimutkaisin**: SHA-256-tarkistussumman todennus, Protobuf-pyynnön koodaus, binaarinen EventStream → SSE-vastauksen jäsennys | -| `codex.ts` | OpenAI Codex | Lisää järjestelmäkäskyjä, hallitsee ajattelutasoja, poistaa ei-tuetut parametrit | -| `gemini-cli.ts` | Google Gemini CLI | Muokatun URL-osoitteen rakentaminen (`streamGenerateContent`), Google OAuth -tunnuksen päivitys | -| `github.ts` | GitHub Copilot | Kaksoistunnistejärjestelmä (GitHub OAuth + Copilot-tunnus), VSCode-otsikon matkiminen | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binäärijäsennys, AMZN-tapahtumakehykset, tunnuksen arviointi | -| `index.ts` | — | Tehdas: karttojen toimittajan nimi → suorittajaluokka, oletusarvolla | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Käsittelijät (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**orkestrointikerros** — koordinoi käännöstä, suoritusta, suoratoistoa ja virheiden käsittelyä. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Tiedosto | Tarkoitus | +| File | Purpose | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Keskiorkesteri** (~600 riviä). Käsittelee koko pyynnön elinkaaren: muodon tunnistus → käännös → suorittimen lähettäminen → suoratoisto/ei-suoratoistovaste → tunnuksen päivitys → virheiden käsittely → käytön loki. | -| `responsesHandler.ts` | Sovitin OpenAI:n Responses API:lle: muuntaa vastausmuodon → Chat Completions → lähettää osoitteeseen `chatCore` → muuntaa SSE:n takaisin Responses-muotoon. | -| `embeddings.ts` | Upottamisen sukupolven käsittelijä: ratkaisee upotusmallin → toimittaja, lähettää palveluntarjoajan API:lle, palauttaa OpenAI-yhteensopivan upotusvastauksen. Tukee 6+ palveluntarjoajia. | -| `imageGeneration.ts` | Kuvanluontikäsittelijä: ratkaisee kuvamallin → palveluntarjoajan, tukee OpenAI-yhteensopivia, Gemini-image- (Antigravity) ja backback (Nebius) -tiloja. Palauttaa base64- tai URL-kuvat. | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Pyydä elinkaarta (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,26 +258,26 @@ sequenceDiagram --- -### 4.4 Palvelut (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Liiketoimintalogiikka, joka tukee käsittelijöitä ja toimeenpanijoita. +Business logic that supports the handlers and executors. -| Tiedosto | Tarkoitus | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `provider.ts` | **Muodon tunnistus** (`detectFormat`): analysoi pyyntörunkorakenteen tunnistaakseen Claude-/OpenAI-/Gemini-/Antigravity-/Responses-muodot (sisältää Clauden `max_tokens`-heuristiikan). Myös: URL-osoitteiden rakentaminen, otsikon rakentaminen, ajatteluasetusten normalisointi. Tukee dynaamisia palveluntarjoajia `openai-compatible-*` ja `anthropic-compatible-*`. | -| `model.ts` | Mallin merkkijonon jäsennys (`claude/model-name` → `{provider: "claude", model: "model-name"}`), aliaksen tarkkuus törmäystunnistuksen kanssa, syötteen puhdistus (hylkää polun läpikulku/ohjausmerkit) ja mallitietojen resoluutio asynkronisen aliaksen hakijan tuella. | -| `accountFallback.ts` | Rate-limit käsittely: eksponentiaalinen backoff (1s → 2s → 4s → max 2min), tilin jäähtymisen hallinta, virheluokitus (jotka virheet laukaisevat varauksen tai eivät). | -| `tokenRefresh.ts` | OAuth-tunnuksen päivitys **jokaiselle palveluntarjoajalle**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Sisältää lennon aikana tapahtuvan lupauksen poistamisen välimuistin ja uudelleenyrityksen eksponentiaalisella peruutuksella. | -| `combo.ts` | **Yhdistelmämallit**: varamallien ketjut. Jos malli A epäonnistuu varautumiskelpoisen virheen vuoksi, kokeile mallia B, sitten C jne. Palauttaa todelliset ylävirran tilakoodit. | -| `usage.ts` | Hakee kiintiö-/käyttötiedot palveluntarjoajan sovellusliittymistä (GitHub Copilot -kiintiöt, Antigravity-mallikiintiöt, Codexin nopeusrajoitukset, Kiron käyttöerittelyt, Claude-asetukset). | -| `accountSelector.ts` | Älykäs tilin valinta pisteytysalgoritmilla: ottaa huomioon prioriteetin, terveydentilan, kiertorajan sijainnin ja jäähtymistilan valitakseen optimaalisen tilin kullekin pyynnölle. | -| `contextManager.ts` | Pyynnön kontekstin elinkaaren hallinta: luo ja seuraa pyyntökohtaisia ​​kontekstiobjekteja metatiedoilla (pyyntötunnus, aikaleimat, palveluntarjoajan tiedot) virheenkorjausta ja lokia varten. | -| `ipFilter.ts` | IP-pohjainen pääsynhallinta: tukee sallittu- ja estolistatiloja. Vahvistaa asiakkaan IP-osoitteen määritettyjen sääntöjen mukaan ennen API-pyyntöjen käsittelemistä. | -| `sessionManager.ts` | Istuntoseuranta asiakkaan sormenjälkien avulla: seuraa aktiivisia istuntoja hajautettujen asiakastunnisteiden avulla, valvoo pyyntöjen määrää ja tarjoaa istuntomittareita. | -| `signatureCache.ts` | Pyynnön allekirjoituspohjainen deduplikoinnin välimuisti: estää päällekkäiset pyynnöt tallentamalla välimuistiin viimeaikaiset pyyntöjen allekirjoitukset ja palauttamalla välimuistissa olevat vastaukset identtisille pyynnöille tietyn aikaikkunan sisällä. | -| `systemPrompt.ts` | Yleinen järjestelmäkehotteen lisäys: liittää kaikkien pyyntöjen edelle tai liittää määritettävän järjestelmäkehotteen palveluntarjoajakohtaisen yhteensopivuuden käsittelyn avulla. | -| `thinkingBudget.ts` | Päättelytunnisteen budjetin hallinta: tukee läpivienti-, automaatti- (kaistaleiden ajattelukonfiguraatio), mukautettua (kiinteä budjetti) ja mukautuva (monimutkaisuusskaalaus) -tiloja ajattelun/päättelyn hallintaan. | -| `wildcardRouter.ts` | Jokerimerkkimallin reititys: ratkaisee jokerimerkkimallit (esim. `*/claude-*`) konkreettisiksi toimittaja/malli-pareiksi saatavuuden ja prioriteetin perusteella. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | #### Token Refresh Deduplication @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Tilin varatilakone +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Yhdistelmämalliketju +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Kääntäjä (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**muotojen käännösmoottori**, joka käyttää itse rekisteröivää laajennusjärjestelmää. +The **format translation engine** using a self-registering plugin system. -#### Arkkitehtuuri +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Hakemisto | Tiedostot | Kuvaus | -| ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `request/` | 8 kääntäjää | Muunna pyyntörungot muotojen välillä. Jokainen tiedosto rekisteröi itse itsensä tuonnin yhteydessä `register(from, to, fn)`:n kautta. | -| `response/` | 7 kääntäjää | Muunna suoratoistovastauspalat muotojen välillä. Käsittelee SSE-tapahtumatyyppejä, ajattelulohkoja, työkalukutsuja. | -| `helpers/` | 6 avustajaa | Jaetut apuohjelmat: `claudeHelper` (järjestelmäkehotteen purkaminen, ajattelukonfiguraatio), `geminiHelper` (osien/sisällön kartoitus), `openaiHelper` (muotosuodatus), `toolCallHelper`), \_TOK-sukupolvi_EN_1, vastaus puuttuu `responsesApiHelper`. | -| `index.ts` | — | Käännöskone: `translateRequest()`, `translateResponse()`, tilanhallinta, rekisteri. | -| `formats.ts` | — | Muotovakiot: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`_, \_\_EN_92_NI, _. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Avainsuunnittelu: Itserekisteröityvät laajennukset +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,17 +395,17 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Utilis (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Tiedosto | Tarkoitus | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Virhevastausten rakentaminen (OpenAI-yhteensopiva muoto), ylävirran virheen jäsennys, Antigravitaatio-uudelleenyritysten poimiminen virheilmoituksista, SSE-virheiden suoratoisto. | -| `stream.ts` | **SSE Transform Stream** — suoratoiston ydinputki. Kaksi tilaa: `TRANSLATE` (täysmuotoinen käännös) ja `PASSTHROUGH` (normalisoi + pura käyttö). Käsittelee osien puskuroinnin, käyttöarvioinnin ja sisällön pituuden seurannan. Virtakohtaiset enkooderi/dekooderiinstanssit välttävät jaetun tilan. | -| `streamHelpers.ts` | Matalan tason SSE-apuohjelmat: `parseSSELine` (välilyöntejä sietävä), `hasValuableContent` (suodattaa tyhjät osat OpenAI:lle/Claudelle/Geminille), `fixInvalidId`, `fixInvalidId`, `perf_metrics` puhdistus). | -| `usageTracking.ts` | Tokenin käytön poiminta mistä tahansa muodosta (Claude/OpenAI/Gemini/Responses), arvio erillisillä työkalu/viestin char-per-token-suhteilla, puskurin lisäys (2000 merkkiä turvamarginaali), muotokohtainen kenttäsuodatus, konsolin kirjaaminen ANSI-väreillä. | -| `requestLogger.ts` | Tiedostopohjainen pyyntöjen kirjaaminen (osallistu osoitteen `ENABLE_REQUEST_LOGS=true` kautta). Luo istuntokansioita numeroiduilla tiedostoilla: `1_req_client.json` → `7_res_client.txt`. Kaikki I/O on async (fire-and-forget). Peittää herkät otsikot. | -| `bypassHandler.ts` | Kaappaa tiettyjä malleja Claude CLI:stä (otsikon poimiminen, lämmittely, laskenta) ja palauttaa vääriä vastauksia soittamatta palveluntarjoajille. Tukee sekä suoratoistoa että ei-suoratoistoa. Tarkoituksella rajoitettu Claude CLI:n soveltamisalaan. | -| `networkProxy.ts` | Ratkaisee tietyn palveluntarjoajan lähtevän välityspalvelimen URL-osoitteen etusijalla: palveluntarjoajakohtainen määritys → globaali määritys → ympäristömuuttujat (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Tukee `NO_PROXY` poissulkemista. Välimuistin konfiguraatio 30 sekuntia. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | #### SSE Streaming Pipeline @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Pyydä Loggerin istuntorakennetta +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Sovelluskerros (`src/`) +### 4.7 Application Layer (`src/`) -| Hakemisto | Tarkoitus | -| ------------- | --------------------------------------------------------------------------------------- | -| `src/app/` | Verkkokäyttöliittymä, API-reitit, Express-väliohjelmisto, OAuth-soittojen käsittelijät | -| `src/lib/` | Tietokannan käyttöoikeus (`localDb.ts`, `usageDb.ts`), todennus, jaettu | -| `src/mitm/` | Man-in-the-middle-välityspalvelinapuohjelmat palveluntarjoajan liikenteen sieppaamiseen | -| `src/models/` | Tietokantamallin määritelmät | -| `src/shared/` | Open-sse-funktioiden kääreet (tarjoaja, virta, virhe jne.) | -| `src/sse/` | SSE-päätepisteen käsittelijät, jotka yhdistävät avoimen SS-kirjaston Express-reiteille | -| `src/store/` | Sovellustilan hallinta | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Merkittäviä API-reitit +#### Notable API Routes -| Reitti | Menetelmät | Tarkoitus | -| --------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------- | -| `/api/provider-models` | HANKI/LÄHETÄ/POISTA | CRUD mukautetuille malleille toimittajakohtaisesti | -| `/api/models/catalog` | HANKI | Koottu luettelo kaikista malleista (chat, upotus, kuva, mukautettu) ryhmitelty tarjoajan mukaan | -| `/api/settings/proxy` | GET/PUT/DELETE | Hierarkkinen lähtevän välityspalvelimen määritys (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Vahvistaa välityspalvelinyhteyden ja palauttaa julkisen IP-osoitteen/latenssin | -| `/v1/providers/[provider]/chat/completions` | POST | Palveluntarjoajakohtaiset keskustelut ja mallin vahvistus | -| `/v1/providers/[provider]/embeddings` | POST | Palveluntarjoajakohtaiset upotukset mallin vahvistuksella | -| `/v1/providers/[provider]/images/generations` | POST | Palveluntarjoajakohtainen kuvien luominen mallin tarkistuksen kanssa | -| `/api/settings/ip-filter` | GET/PUT | IP-sallittujen/estoluetteloiden hallinta | -| `/api/settings/thinking-budget` | GET/PUT | Päättelytunnuksen budjetin määritys (passthrough/auto/custom/adaptive) | -| `/api/settings/system-prompt` | GET/PUT | Globaali järjestelmän pikainjektio kaikkiin pyyntöihin | -| `/api/sessions` | HANKI | Aktiivisen istunnon seuranta ja mittarit | -| `/api/rate-limits` | HANKI | Tilikohtaisen koron rajan tila | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- ## 5. Key Design Patterns -### 5.1 Hub-and-Spoke -käännös +### 5.1 Hub-and-Spoke Translation -Kaikki muodot käännetään **OpenAI-muodon kautta keskittimenä**. Uuden palveluntarjoajan lisääminen edellyttää vain **yksi parin** kirjoittamista (OpenAI:lle/OpenAI:sta), ei N paria. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Toteuttajastrategiamalli +### 5.2 Executor Strategy Pattern -Jokaisella palveluntarjoajalla on oma suorittajaluokka, joka perii `BaseExecutor`. Tehdas kohteessa `executors/index.ts` valitsee oikean suorituksen aikana. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Itserekisteröivä laajennusjärjestelmä +### 5.3 Self-Registering Plugin System -Kääntäjämoduulit rekisteröivät itsensä tuontia varten osoitteessa `register()`. Uuden kääntäjän lisääminen on vain tiedoston luomista ja sen tuomista. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Tilin palautus eksponentiaalisella backoffilla +### 5.4 Account Fallback with Exponential Backoff -Kun palveluntarjoaja palauttaa numeron 429/401/500, järjestelmä voi siirtyä seuraavalle tilille käyttämällä eksponentiaalisia viilennyksiä (1 s → 2 s → 4 s → max 2 min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 yhdistelmämalliketjut +### 5.5 Combo Model Chains -"Yhdistelmä" ryhmittelee useita `provider/model` merkkijonoja. Jos ensimmäinen epäonnistuu, palaa automaattisesti seuraavaan. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Tilallinen suoratoistokäännös +### 5.6 Stateful Streaming Translation -Vastauskäännös säilyttää tilan SSE-paloissa (ajattelulohkojen seuranta, työkalukutsujen kerääminen, sisältölohkojen indeksointi) `initState()`-mekanismin kautta. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Käyttöturvapuskuri +### 5.7 Usage Safety Buffer -Raportoituun käyttöön lisätään 2 000 tunnuksen puskuri, joka estää asiakkaita saavuttamasta kontekstiikkunan rajoja järjestelmäkehotteiden ja muotojen käännöksen aiheuttaman ylimääräisen rasituksen vuoksi. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Tuetut muodot +## 6. Supported Formats -| Muoto | Suunta | Tunniste | -| -------------------------------------- | ------------- | ------------------ | -| OpenAI-keskustelun loppuun saattaminen | lähde + kohde | `openai` | -| OpenAI Responses API | lähde + kohde | `openai-responses` | -| Antrooppinen Claude | lähde + kohde | `claude` | -| Google Gemini | lähde + kohde | `gemini` | -| Google Gemini CLI | vain kohde | `gemini-cli` | -| Antigravitaatio | lähde + kohde | `antigravity` | -| AWS Kiro | vain kohde | `kiro` | -| Kursori | vain kohde | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Tuetut palveluntarjoajat +## 7. Supported Providers -| Palveluntarjoaja | Todennusmenetelmä | Toteuttaja | Tärkeimmät huomautukset | -| ------------------------ | ------------------------- | --------------- | ---------------------------------------------------------- | -| Antrooppinen Claude | API-avain tai OAuth | Oletus | Käyttää `x-api-key`-otsikkoa | -| Google Gemini | API-avain tai OAuth | Oletus | Käyttää `x-goog-api-key`-otsikkoa | -| Google Gemini CLI | OAuth | GeminiCLI | Käyttää `streamGenerateContent` päätepistettä | -| Antigravitaatio | OAuth | Antigravitaatio | Usean URL-osoitteen varaosa, mukautettu jäsennys uudelleen | -| OpenAI | API-avain | Oletus | Vakiosiirtotodennus | -| Codex | OAuth | Codex | Ruiskuttaa järjestelmäohjeita, hallitsee ajattelua | -| GitHub Copilot | OAuth + Copilot-tunnus | Github | Kaksoistunnus, VSCode-otsikkoa jäljittelevä | -| Kiro (AWS) | AWS SSO OIDC tai Social | Kiro | Binäärinen EventStream-jäsennys | -| Kohdistin IDE | Tarkistussumma auth | Kursori | Protobuf-koodaus, SHA-256-tarkistussummat | -| Qwen | OAuth | Oletus | Vakiotodennus | -| iFlow | OAuth (Perus + siirtotie) | Oletus | Dual auth otsikko | -| OpenRouter | API-avain | Oletus | Vakiosiirtotodennus | -| GLM, Kimi, MiniMax | API-avain | Oletus | Claude-yhteensopiva, käytä `x-api-key` | -| `openai-compatible-*` | API-avain | Oletus | Dynaaminen: mikä tahansa OpenAI-yhteensopiva päätepiste | -| `anthropic-compatible-*` | API-avain | Oletus | Dynaaminen: mikä tahansa Claude-yhteensopiva päätepiste | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Tietovirran yhteenveto +## 8. Data Flow Summary -### Suoratoistopyyntö +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Ei-suoratoistopyyntö +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Ohitusvirtaus (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/fi/FEATURES.md b/docs/i18n/fi/FEATURES.md index 923fcfbc6b..82cc73b67b 100644 --- a/docs/i18n/fi/FEATURES.md +++ b/docs/i18n/fi/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Kojelaudan ominaisuuksien galleria +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Visuaalinen opas OmniRoute-hallintapaneelin jokaiseen osioon. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Palveluntarjoajat +## 🔌 Providers -Hallinnoi AI-palveluntarjoajan yhteyksiä: OAuth-palveluntarjoajat (Claude Code, Codex, Gemini CLI), API-avaintoimittajat (Groq, DeepSeek, OpenRouter) ja ilmaiset palveluntarjoajat (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Yhdistelmät +## 🎨 Combos -Luo mallin reitityskomboja kuudella strategialla: täytä ensin, round-robin, kahden valinnan teho, satunnainen, vähiten käytetty ja kustannusoptimoitu. Jokainen yhdistelmä ketjuttaa useita malleja automaattisella varalla. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Analytiikka +## 📊 Analytics -Kattava käyttöanalytiikka tunnuksen kulutuksella, kustannusarvioilla, aktiivisuuslämpökartoilla, viikoittaisilla jakelukaavioilla ja palveluntarjoajakohtaisilla erittelyillä. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Järjestelmän terveys +## 🏥 System Health -Reaaliaikainen seuranta: käyttöaika, muisti, versio, latenssiprosenttipisteet (p50/p95/p99), välimuistitilastot ja palveluntarjoajan katkaisijan tilat. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Kääntäjän leikkikenttä +## 🔧 Translator Playground -Neljä tilaa API-käännösten virheenkorjaukseen: **Playground** (muodonmuunnin), **Chat Tester** (livepyynnöt), **Test Bench** (erätestit) ja **Live Monitor** (reaaliaikainen suoratoisto). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Asetukset +## 🎮 Model Playground _(v2.0.9+)_ -Yleiset asetukset, järjestelmän tallennus, varmuuskopioiden hallinta (vienti/tuonti tietokanta), ulkonäkö (tumma/vaalea tila), suojaus (sisältää API-päätepisteiden suojauksen ja mukautetun palveluntarjoajan eston), reititys, joustavuus ja edistyneet asetukset. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI-työkalut +## 🔧 CLI Tools -Yhden napsautuksen konfigurointi AI-koodaustyökaluille: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code ja Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Pyyntölokit +## 🤖 CLI Agents _(v2.0.11+)_ -Reaaliaikainen pyyntöjen kirjaaminen suodatuksella palveluntarjoajan, mallin, tilin ja API-avaimen mukaan. Näyttää tilakoodit, tunnuksen käytön, viiveen ja vastaustiedot. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API-päätepiste +## 🌐 API Endpoint -Yhdistetty API-päätepisteesi ominaisuuksien erittelyllä: keskustelujen loppuunsaattaminen, upotukset, kuvien luominen, uudelleensijoitus, äänen transkriptio ja rekisteröidyt API-avaimet. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/fi/TROUBLESHOOTING.md b/docs/i18n/fi/TROUBLESHOOTING.md index 47cae11882..120092d63c 100644 --- a/docs/i18n/fi/TROUBLESHOOTING.md +++ b/docs/i18n/fi/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Vianetsintä +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -OmniRouten yleisiä ongelmia ja ratkaisuja. +Common problems and solutions for OmniRoute. --- -## Pikakorjauksia +## Quick Fixes -| Ongelma | Ratkaisu | -| ---------------------------------- | --------------------------------------------------------------------------- | -| Ensimmäinen kirjautuminen ei toimi | Tarkista `INITIAL_PASSWORD` kohteessa `.env` (oletus: `123456`) | -| Kojelauta avautuu väärään porttiin | Aseta `PORT=20128` ja `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Ei pyyntölokeja alle `logs/` | Aseta `ENABLE_REQUEST_LOGS=true` | -| EACCES: lupa evätty | Aseta `DATA_DIR=/path/to/writable/dir` ohittamaan `~/.omniroute` | -| Reititysstrategia ei tallennu | Päivitys versioon 1.4.11+ (Zod-skeeman korjaus asetusten pysyvyyttä varten) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Palveluntarjoajan ongelmat +## Provider Issues -### "Kielimalli ei antanut viestejä" +### "Language model did not provide messages" -**Syy:** Palveluntarjoajan kiintiö käytetty. +**Cause:** Provider quota exhausted. -**Korjaa:** +**Fix:** -1. Tarkista kojelaudan kiintiöiden seuranta -2. Käytä yhdistelmää varatasoilla -3. Vaihda halvempaan/ilmaiseen tasoon +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Hintarajoitus +### Rate Limiting -**Syy:** Tilauskiintiö käytetty. +**Cause:** Subscription quota exhausted. -**Korjaa:** +**Fix:** -- Lisää vara: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Käytä GLM/MiniMaxia halvana varmuuskopiona +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth-tunnus vanhentunut +### OAuth Token Expired -OmniRoute päivittää tunnukset automaattisesti. Jos ongelmat jatkuvat: +OmniRoute auto-refreshes tokens. If issues persist: -1. Kojelauta → Palveluntarjoaja → Yhdistä uudelleen -2. Poista ja lisää palveluntarjoajan yhteys uudelleen +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Pilviongelmat +## Cloud Issues -### Pilven synkronointivirheet +### Cloud Sync Errors -1. Vahvista `BASE_URL` pistettä käynnissä olevaan esiintymääsi (esim. `http://localhost:20128`) -2. Vahvista `CLOUD_URL` pistettä pilvipäätepisteeseesi (esim. `https://omniroute.dev`) -3. Pidä `NEXT_PUBLIC_*`-arvot kohdakkain palvelinpuolen arvojen kanssa +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Pilvi `stream=false` Palauttaa 500 +### Cloud `stream=false` Returns 500 -**Oire:** `Unexpected token 'd'...` pilvipäätepisteessä muille kuin suoratoistopuheluille. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Syy:** Upstream palauttaa SSE-hyötykuorman, kun asiakas odottaa JSONia. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Ratkaisu:** Käytä `stream=true` pilvisuorapuheluihin. Paikallinen suoritusaika sisältää SSE→JSON-varavaihtoehdon. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud sanoo Yhdistetty, mutta "Virheellinen API-avain" +### Cloud Says Connected but "Invalid API key" -1. Luo uusi avain paikallisesta hallintapaneelista (`/api/keys`) -2. Suorita pilvisynkronointi: Ota pilvi käyttöön → Synkronoi nyt -3. Vanhat/synkronoimattomat avaimet voivat edelleen palauttaa `401` pilvessä +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Docker-ongelmat +## Docker Issues -### CLI-työkalu näyttää, ettei sitä ole asennettu +### CLI Tool Shows Not Installed -1. Tarkista suoritusaikakentät: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Kannettava tila: käytä kuvakohdetta `runner-cli` (yhdistetyt CLI:t) -3. Isäntäliitostila: aseta `CLI_EXTRA_PATHS` ja liitä isäntälokerohakemisto vain luku -muotoiseksi -4. Jos `installed=true` ja `runnable=false`: binaari löytyi, mutta kuntotarkastus epäonnistui +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Nopea ajonaikainen validointi +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Kustannusongelmat +## Cost Issues -### Korkeat kustannukset +### High Costs -1. Tarkista käyttötilastot kohdassa Dashboard → Usage -2. Vaihda ensisijaiseksi malliksi GLM/MiniMax -3. Käytä ilmaista tasoa (Gemini CLI, iFlow) ei-kriittisiin tehtäviin -4. Aseta kustannusbudjetit API-avainta kohti: Dashboard → API Keys → Budget +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Virheenkorjaus +## Debugging -### Ota pyyntölokit käyttöön +### Enable Request Logs -Aseta `ENABLE_REQUEST_LOGS=true` tiedostossasi `.env`. Lokit näkyvät hakemistossa `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Tarkista palveluntarjoajan kunto +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Ajonaikainen tallennus +### Runtime Storage -- Päätila: `${DATA_DIR}/db.json` (palveluntarjoajat, yhdistelmät, aliakset, avaimet, asetukset) -- Käyttö: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Pyyntölokit: `/logs/...` (kun `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Virtakatkaisijaongelmat +## Circuit Breaker Issues -### Palveluntarjoaja jumissa OPEN-tilassa +### Provider stuck in OPEN state -Kun palveluntarjoajan katkaisija on AUKI, pyynnöt estetään, kunnes jäähdytys päättyy. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Korjaa:** +**Fix:** -1. Siirry kohtaan **Käyttöpaneeli → Asetukset → Resilience** -2. Tarkista asianomaisen palveluntarjoajan katkaisijakortti -3. Napsauta **Nollaa kaikki** tyhjentääksesi kaikki katkaisijat tai odota jäähdytysajan päättymistä -4. Varmista, että palveluntarjoaja on todella saatavilla, ennen kuin nollaat +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Palveluntarjoaja laukeaa jatkuvasti katkaisijan +### Provider keeps tripping the circuit breaker -Jos palveluntarjoaja siirtyy toistuvasti OPEN-tilaan: +If a provider repeatedly enters OPEN state: -1. Tarkista vikakuvio kohdasta **Dashboard → Health → Provider Health** -2. Siirry kohtaan **Settings → Resilience → Provider Profiles** ja nosta vikakynnystä. -3. Tarkista, onko palveluntarjoaja muuttanut API-rajoja tai vaatiiko todennuksen uudelleen -4. Tarkista viiveen telemetria — korkea latenssi voi aiheuttaa aikakatkaisuun perustuvia virheitä +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Äänen transkriptioongelmat +## Audio Transcription Issues -### "Ei tuettu malli" -virhe +### "Unsupported model" error -- Varmista, että käytät oikeaa etuliitettä: `deepgram/nova-3` tai `assemblyai/best` -- Varmista, että palveluntarjoaja on yhdistetty kohdassa **Dashboard → Providers** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Transkriptio palautetaan tyhjänä tai epäonnistuu +### Transcription returns empty or fails -- Tarkista tuetut äänimuodot: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Varmista, että tiedostokoko on palveluntarjoajan rajoissa (yleensä < 25 Mt) -- Tarkista palveluntarjoajan API-avaimen voimassaolo toimittajakortista +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Kääntäjän virheenkorjaus +## Translator Debugging -Käytä **Käyttöpaneeli → Kääntäjä** muotojen käännösongelmien korjaamiseen: +Use **Dashboard → Translator** to debug format translation issues: -| Tila | Milloin käyttää | -| ------------------------- | ------------------------------------------------------------------------------------------------------- | -| **Leikkikenttä** | Vertaa syöttö-/tulostusmuotoja rinnakkain – liitä epäonnistunut pyyntö nähdäksesi, miten se käännetään | -| **Pikaviestien testaaja** | Lähetä reaaliaikaisia ​​viestejä ja tarkasta koko pyynnön/vastauksen hyötykuorma, mukaan lukien otsikot | -| **Testipenkki** | Suorita erätestejä muotoyhdistelmille selvittääksesi, mitkä käännökset ovat rikki | -| **Live Monitor** | Tarkkaile reaaliaikaista pyyntövirtaa havaitaksesi ajoittaiset käännösongelmat | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Yleisiä muotoongelmia +### Common format issues -- **Ajattelevat tunnisteet eivät näy** — Tarkista, tukeeko kohdetoimittaja ajattelua ja ajattelun budjettiasetusta -- **Työkalukutsujen pudottaminen** — Jotkin muotokäännökset voivat poistaa ei-tuetut kentät. vahvista leikkikenttätilassa -- **Järjestelmäkehote puuttuu** — Claude ja Gemini kahvajärjestelmä kehottaa eri tavalla; tarkista käännöstulos -- **SDK palauttaa raakamerkkijonon objektin sijaan** — Korjattu versiossa 1.1.0: vastauspuhdistin poistaa nyt epästandardit kentät (`x_groq`, `usage_breakdown` jne.), jotka aiheuttavat OpenAI SDK Pydantic -tarkistusvirheitä -- **GLM/ERNIE hylkää roolin `system`** — Korjattu versiossa 1.1.0: roolin normalisoija yhdistää automaattisesti järjestelmäviestit käyttäjän viesteiksi yhteensopimattomissa malleissa -- **`developer` roolia ei tunnistettu** - Korjattu versiossa 1.1.0: muunnetaan automaattisesti muotoon `system` muille kuin OpenAI-palveluntarjoajille -- **`json_schema` ei toimi Geminin kanssa** — Korjattu versiossa 1.1.0: `response_format` muunnetaan nyt Geminin `responseMimeType` + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Kestävyysasetukset +## Resilience Settings -### Automaattinen nopeusrajoitus ei laukea +### Auto rate-limit not triggering -- Automaattinen nopeusrajoitus koskee vain API-avainten toimittajia (ei OAuth-tilausta) -- Varmista, että **Asetukset → Resilienssi → Palveluntarjoajan profiilit** on automaattinen rajoitus käytössä -- Tarkista, palauttaako palveluntarjoaja `429`-tilakoodit tai `Retry-After`-otsikot +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Viritys eksponentiaalisesti +### Tuning exponential backoff -Palveluntarjoajan profiilit tukevat näitä asetuksia: +Provider profiles support these settings: -- **Perusviive** — Ensimmäinen odotusaika ensimmäisen epäonnistumisen jälkeen (oletus: 1 s) -- **Maksimiviive** - Odotusajan enimmäisraja (oletus: 30 s) -- **Kerroin** — Kuinka paljon viivettä lisätään peräkkäistä vikaa kohti (oletus: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Ukkosta estävä lauma +### Anti-thundering herd -Kun monet samanaikaiset pyynnöt osuvat nopeusrajoitettuun palveluntarjoajaan, OmniRoute käyttää mutex + automaattista nopeuden rajoitusta sarjoittamaan pyynnöt ja estämään peräkkäiset epäonnistumiset. Tämä on automaattinen API-avainten tarjoajille. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Vieläkö jumissa? +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub-ongelmat**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arkkitehtuuri**: Katso sisäiset tiedot kohdasta [link](ARCHITECTURE.md) -- **API-viite**: Katso kaikki päätepisteet kohdasta [link](API_REFERENCE.md) -- **Health Dashboard**: Tarkista järjestelmän reaaliaikainen tila kohdasta **Dashboard → Health** -- **Kääntäjä**: Käytä **Käyttöpaneeli → Kääntäjä** muotoongelmien korjaamiseen +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/fi/USER_GUIDE.md b/docs/i18n/fi/USER_GUIDE.md index a665111bd9..5a043224df 100644 --- a/docs/i18n/fi/USER_GUIDE.md +++ b/docs/i18n/fi/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Käyttöopas +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Täydellinen opas palveluntarjoajien määrittämiseen, yhdistelmien luomiseen, CLI-työkalujen integrointiin ja OmniRouten käyttöönottoon. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Sisällysluettelo +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Täydellinen opas palveluntarjoajien määrittämiseen, yhdistelmien luomiseen, --- -## 💰 Hinnoittelu yhdellä silmäyksellä +## 💰 Pricing at a Glance -| Taso | Palveluntarjoaja | Kustannukset | Kiintiön nollaus | Paras | -| ---------------- | ----------------- | -------------------- | ---------------------- | -------------------------- | -| **💳 TILAUS** | Claude Code (Pro) | 20 dollaria/kk | 5h + viikoittain | jo tilattu | -| | Codex (Plus/Pro) | 20-200 $/kk | 5h + viikoittain | OpenAI-käyttäjät | -| | Gemini CLI | **ILMAINEN** | 180 tk/kk + 1 tk/päivä | Kaikki! | -| | GitHub Copilot | 10-19 $/kk | Kuukausittain | GitHub-käyttäjät | -| **🔑 API-AVAIN** | DeepSeek | Maksu per käyttö | Ei yhtään | Halpa perustelu | -| | Groq | Maksu per käyttö | Ei yhtään | Erittäin nopea johtopäätös | -| | xAI (Grok) | Maksu per käyttö | Ei yhtään | Grok 4 perustelut | -| | Mistral | Maksu per käyttö | Ei yhtään | EU:n isännöimät mallit | -| | Hämmennys | Maksu per käyttö | Ei yhtään | Haku-lisätty | -| | Yhdessä AI | Maksu per käyttö | Ei yhtään | Avoimen lähdekoodin mallit | -| | Ilotulitus AI | Maksu per käyttö | Ei yhtään | Nopeat FLUX-kuvat | -| | Aivot | Maksu per käyttö | Ei yhtään | Kiekon mittakaavanopeus | -| | Cohere | Maksu per käyttö | Ei yhtään | Komento R+ RAG | -| | NVIDIA NIM | Maksu per käyttö | Ei yhtään | Yritysmallit | -| **💰 EDULLISET** | GLM-4.7 | 0,6 $/1 milj. | Päivittäin klo 10 | Budjetin varmuuskopio | -| | MiniMax M2.1 | 0,2 $/1 milj. | 5 tunnin rullaus | Halvin vaihtoehto | -| | Kimi K2 | 9 dollaria/kk asunto | 10 milj. rahakkeita/kk | Ennustettavat kustannukset | -| **🆓 ILMAINEN** | iFlow | 0 dollaria | Rajoittamaton | 8 mallia ilmaiseksi | -| | Qwen | 0 dollaria | Rajoittamaton | 3 mallia ilmaiseksi | -| | Kiro | 0 dollaria | Rajoittamaton | Claude ilmaiseksi | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Pro-vinkki:** Aloita Gemini CLI:llä (180 000 ilmaista kuukaudessa) + iFlow (rajoittamaton ilmainen) -yhdistelmä = 0 dollarin hinta! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Käyttökotelot +## 🎯 Use Cases -### Tapaus 1: "Minulla on Claude Pro -tilaus" +### Case 1: "I have Claude Pro subscription" -**Ongelma:** Kiintiö vanhenee käyttämättä, nopeusrajoitukset raskaan koodauksen aikana +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Tapaus 2: "Haluan ilman kustannuksia" +### Case 2: "I want zero cost" -**Ongelma:** Ei ole varaa tilauksiin, tarvitaan luotettavaa tekoälykoodausta +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Tapaus 3: "Tarvitsen 24/7-koodausta, ei keskeytyksiä" +### Case 3: "I need 24/7 coding, no interruptions" -**Ongelma:** Määräajat, seisokkeihin ei ole varaa +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Tapaus 4: "Haluan ILMAISTA tekoälyä OpenClawissa" +### Case 4: "I want FREE AI in OpenClaw" -**Ongelma:** Tarvitset AI-avustajan viestisovelluksissa, täysin ilmainen +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Palveluntarjoajan asetukset +## 📖 Provider Setup -### 🔐 Tilauspalveluntarjoajat +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Provinkki:** Käytä Opusta monimutkaisiin tehtäviin ja Sonnetia nopeutta varten. OmniRoute jäljityskiintiö mallia kohden! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (ILMAINEN 180 000/kk!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,7 +152,7 @@ Models: gc/gemini-2.5-pro ``` -**Paras hinta-laatusuhde:** Valtava ilmainen taso! Käytä tätä ennen maksettuja tasoja. +**Best Value:** Huge free tier! Use this before paid tiers. #### GitHub Copilot @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Halvat palveluntarjoajat +### 💰 Cheap Providers -#### GLM-4.7 (päivittäinen nollaus, 0,6 $/1 milj.) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Rekisteröidy: [Zhipu AI](https://open.bigmodel.cn/) -2. Hanki API-avain Coding Planista -3. Hallintapaneeli → Lisää API-avain: Palveluntarjoaja: `glm`, API-avain: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Käytä:** `glm/glm-4.7` — **Provinkki:** Koodaussuunnitelma tarjoaa 3× kiintiön 1/7 hinnalla! Nollaa päivittäin klo 10.00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 h nollaus, 0,20 $/1 milj.) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Rekisteröidy: [MiniMax](https://www.minimax.io/) -2. Hanki API-avain → Dashboard → Add API Key +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Käytä:** `minimax/MiniMax-M2.1` — **Ammattilaisen vinkki:** Halvin vaihtoehto pitkälle kontekstille (1 milj. merkkiä)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (9 dollaria/kk asunto) +#### Kimi K2 ($9/month flat) -1. Tilaa: [Moonshot AI](https://platform.moonshot.ai/) -2. Hanki API-avain → Dashboard → Add API Key +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Käyttö:** `kimi/kimi-latest` — **Ammattilaisen vinkki:** Kiinteä 9 dollaria kuukaudessa 10 miljoonalle rahakkeelle = 0,90 dollaria / 1 miljoona todellista hintaa! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 ILMAISIA palveluntarjoajia +### 🆓 FREE Providers -#### iFlow (8 ILMAISTA mallia) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 ILMAISTA mallia) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude ILMAINEN) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Yhdistelmät +## 🎨 Combos -### Esimerkki 1: Maksimoi tilaus → Halpa varmuuskopio +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Esimerkki 2: Vain ilmainen (nollahinta) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI-integraatio +## 🔧 CLI Integration -### Kohdistimen IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -262,7 +262,7 @@ Settings → Models → Advanced: ### Claude Code -Muokkaa `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Muokkaa `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,7 +303,7 @@ Muokkaa `~/.openclaw/openclaw.json`: } ``` -**Tai käytä Dashboardia:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config ### Cline / Continue / RooCode @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Käyttöönotto +## 🚀 Deployment -### VPS-käyttöönotto +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Katso isäntäintegroitu tila CLI-binaarien kanssa pääasiakirjojen Docker-osiosta. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Ympäristömuuttujat +### Environment Variables -| Muuttuja | Oletus | Kuvaus | -| --------------------- | ------------------------------------ | -------------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT:n allekirjoitussalaisuus (**muutos tuotannossa**) | -| `INITIAL_PASSWORD` | `123456` | Ensimmäisen kirjautumisen salasana | -| `DATA_DIR` | `~/.omniroute` | Tietohakemisto (db, käyttö, lokit) | -| `PORT` | oletuskehys | Huoltoportti (`20128` esimerkeissä) | -| `HOSTNAME` | oletuskehys | Sido isäntä (Dockerin oletusarvo on `0.0.0.0`) | -| `NODE_ENV` | ajonaikainen oletus | Aseta `production` käyttöönottoa varten | -| `BASE_URL` | `http://localhost:20128` | Palvelinpuolen sisäinen perus-URL | -| `CLOUD_URL` | `https://omniroute.dev` | Pilvisynkronoinnin päätepisteen perus-URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Luotujen API-avaimien HMAC-salaisuus | -| `REQUIRE_API_KEY` | `false` | Pakota Bearer API-avain `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Ottaa käyttöön pyyntö-/vastauslokit | -| `AUTH_COOKIE_SECURE` | `false` | Pakota `Secure` todennuseväste (HTTPS-käänteisen välityspalvelimen takana) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Täydellinen ympäristömuuttujaviittaus on kohdassa [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Saatavilla olevat mallit +## 📊 Available Models
-Näytä kaikki saatavilla olevat mallit +View all available models **Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Koodi (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** – ILMAISEKSI: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** – 0,6 $/1 milj.: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** – 0,2 $/1 milj.: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** – ILMAISEKSI: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** – ILMAISEKSI: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** – ILMAISEKSI: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,15 +460,15 @@ Täydellinen ympäristömuuttujaviittaus on kohdassa [README](../README.md). **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Epäselvyys (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Yhdessä AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Ilotulitus AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Aivot (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Yhdenmukainen (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Täydellinen ympäristömuuttujaviittaus on kohdassa [README](../README.md). --- -## 🧩 Lisäominaisuudet +## 🧩 Advanced Features -### Mukautetut mallit +### Custom Models -Lisää mikä tahansa mallitunnus mille tahansa palveluntarjoajalle odottamatta sovelluspäivitystä: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Tai käytä Dashboardia: **Providers → [Provider] → Custom Models**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Palveluntarjoajan reitit +### Dedicated Provider Routes -Reititä pyynnöt suoraan tietylle palveluntarjoajalle mallin validoinnilla: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Palveluntarjoajan etuliite lisätään automaattisesti, jos se puuttuu. Yhteensopimattomat mallit palauttavat `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Verkkovälityspalvelimen asetukset +### Network Proxy Configuration ```bash # Set global proxy @@ -463,7 +522,7 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Ensisijaisuus:** Avainkohtainen → Yhdistelmäkohtainen → Palveluntarjoajakohtainen → Globaali → Ympäristö. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. ### Model Catalog API @@ -471,68 +530,68 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ curl http://localhost:20128/api/models/catalog ``` -Palauttaa mallit ryhmiteltyinä tarjoajan mukaan tyypeillä (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). ### Cloud Sync -- Synkronoi palveluntarjoajat, yhdistelmät ja asetukset eri laitteiden välillä -- Automaattinen taustasynkronointi aikakatkaisulla + Fast Fast -- Valitse palvelinpuolen `BASE_URL`/`CLOUD_URL` tuotannossa +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (vaihe 9) +### LLM Gateway Intelligence (Phase 9) -- **Semanttinen välimuisti** — Tallentaa automaattisesti välimuistiin ei-suoratoistoa, lämpötila = 0 vastausta (ohita `X-OmniRoute-No-Cache: true`) -- **Request Idempotency** – Poistaa pyyntöjen päällekkäisyydet 5 sekunnissa `Idempotency-Key`- tai `X-Request-Id`-otsikon kautta -- **Edistyksen seuranta** — Ota SSE `event: progress` -tapahtumat käyttöön `X-OmniRoute-Progress: true`-otsikon kautta +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Kääntäjän leikkikenttä +### Translator Playground -Pääsy **Dashboard → Kääntäjän** kautta. Tee virheenkorjaus ja visualisoi, kuinka OmniRoute kääntää API-pyynnöt palveluntarjoajien välillä. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Tila | Tarkoitus | -| ------------------------- | ---------------------------------------------------------------------------------------- | -| **Leikkikenttä** | Valitse lähde-/kohdemuodot, liitä pyyntö ja näet käännetyn tulosteen välittömästi | -| **Pikaviestien testaaja** | Lähetä live-chat-viestejä välityspalvelimen kautta ja tarkista koko pyyntö-/vastausjakso | -| **Testipenkki** | Suorita erätestejä useille muotoyhdistelmille varmistaaksesi käännöksen oikeellisuuden | -| **Live Monitor** | Katso reaaliaikaisia ​​käännöksiä, kun pyynnöt kulkevat välityspalvelimen kautta | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Käyttötapaukset:** +**Use cases:** -- Selvitä, miksi tietty asiakas/toimittaja-yhdistelmä epäonnistuu -- Varmista, että ajattelutunnisteet, työkalukutsut ja järjestelmäkehotteet käännetään oikein -- Vertaa muotoeroja OpenAI-, Claude-, Gemini- ja Responses API -muotojen välillä +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Reititysstrategiat +### Routing Strategies -Määritä kohdasta **Kojelauta → Asetukset → Reititys**. +Configure via **Dashboard → Settings → Routing**. -| Strategia | Kuvaus | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | -| **Täytä ensin** | Käyttää tilejä tärkeysjärjestyksessä — ensisijainen tili käsittelee kaikki pyynnöt, kunnes ne eivät ole käytettävissä | -| **Round Robin** | Selaa kaikki tilit, joilla on määritettävissä oleva rajoitus (oletus: 3 puhelua tiliä kohden) | -| **P2C (Kahden valinnan teho)** | Valitsee 2 satunnaista tiliä ja reitit terveempään tiliin – tasapainottaa kuormituksen terveystietoisuuden kanssa | -| **Satunnainen** | Valitsee satunnaisesti tilin kullekin pyynnölle käyttämällä Fisher-Yates shuffle | -| **Vähiten käytetty** | Reitit tilille, jolla on vanhin `lastUsedAt` aikaleima, jakaen liikenteen tasaisesti | -| **Kustannusoptimoitu** | Reitit tilille, jolla on alhaisin prioriteettiarvo, optimointi edullisimpien palveluntarjoajien mukaan | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Jokerimerkkimallin aliakset +#### Wildcard Model Aliases -Luo jokerimerkkikuvioita mallien nimien yhdistämiseksi uudelleen: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Jokerimerkit tukevat `*` (kaikki merkit) ja `?` (yksi merkki). +Wildcards support `*` (any characters) and `?` (single character). -#### Varaketjut +#### Fallback Chains -Määritä maailmanlaajuiset varaketjut, jotka koskevat kaikkia pyyntöjä: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Kestävyys ja katkaisijat +### Resilience & Circuit Breakers -Määritä kohdasta **Kojelauta → Asetukset → Resilience**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute toteuttaa toimittajatason joustavuutta neljällä osalla: +OmniRoute implements provider-level resilience with four components: -1. **Toimittajan profiilit** — Palveluntarjoajakohtainen määritys: - - Vikakynnys (kuinka monta vikaa ennen avaamista) - - Jäähdytyskesto - - Nopeusrajan tunnistusherkkyys - - Eksponentiaaliset peruutusparametrit +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Muokattavat nopeusrajoitukset** — Järjestelmätason oletusasetukset, jotka voidaan määrittää kojelaudassa: - - **Pyynnöt minuutissa (RPM)** – Pyyntöjen enimmäismäärä minuutissa per tili - - **Pyyntöjen välinen vähimmäisaika** - pyyntöjen välinen vähimmäisero millisekunteina - - **Samanaikaisten pyyntöjen enimmäismäärä** — Samanaikaisten pyyntöjen enimmäismäärä tiliä kohden - - Napsauta **Muokkaa** muokataksesi ja sitten **Tallenna** tai **Peruuta**. Arvot säilyvät resilience API:n kautta. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** – Seuraa vikoja palveluntarjoajakohtaisesti ja avaa piirin automaattisesti, kun kynnys saavutetaan: - - **SULJETTU** (terve) — Pyynnöt kulkevat normaalisti - - **AUKI** — Palveluntarjoaja on tilapäisesti estetty toistuvien vikojen jälkeen - - **HALF_OPEN** — Testataan, onko palveluntarjoaja palautunut +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Policies & Locked Identifiers** — Näyttää katkaisijan tilan ja lukitut tunnisteet, joissa on pakko-avaaminen. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Automaattinen nopeusrajoituksen tunnistus** — Valvoo `429`- ja `Retry-After`-otsikoita välttääkseen ennakoivasti palveluntarjoajan nopeusrajojen ylittymisen. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Ammattilaisen vinkki:** Käytä **Nollaa kaikki** -painiketta tyhjentääksesi kaikki katkaisijat ja jäähdytykset, kun palveluntarjoaja toipuu katkosta. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Tietokannan vienti/tuonti +### Database Export / Import -Hallitse tietokannan varmuuskopioita kohdassa **Käyttöpaneeli → Asetukset → Järjestelmä ja tallennus**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Toiminta | Kuvaus | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Vie tietokanta** | Lataa nykyisen SQLite-tietokannan `.sqlite`-tiedostona | -| **Vie kaikki (.tar.gz)** | Lataa täyden varmuuskopioarkiston, joka sisältää: tietokannan, asetukset, yhdistelmät, palveluntarjoajan yhteydet (ei tunnistetietoja), API-avaimen metatiedot | -| **Tuo tietokanta** | Lataa `.sqlite`-tiedosto nykyisen tietokannan tilalle. Tuontia edeltävä varmuuskopio luodaan automaattisesti | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Tuonnin vahvistus:** Tuodun tiedoston eheys (SQLite pragma check), vaaditut taulukot (`provider_connections`, `provider_nodes`, `combos`, ) ja koko 0 (0 MB) tarkistetaan. +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Käyttötapaukset:** +**Use Cases:** -- Siirrä OmniRoute koneiden välillä -- Luo ulkoisia varmuuskopioita katastrofipalautusta varten -- Jaa kokoonpanot tiimin jäsenten välillä (vie kaikki → jaa arkisto) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Asetukset Dashboard +### Settings Dashboard -Asetussivu on järjestetty viiteen välilehteen navigoinnin helpottamiseksi: +The settings page is organized into 5 tabs for easy navigation: -| Välilehti | Sisältö | -| ----------------- | --------------------------------------------------------------------------------------------------------------- | -| **Turvallisuus** | Kirjautumis-/salasana-asetukset, IP-käytön valvonta, API-todennus kohteelle `/models` ja palveluntarjoajan esto | -| **Reititys** | Globaali reititysstrategia (6 vaihtoehtoa), jokerimerkkimallien aliakset, varaketjut, yhdistelmäoletukset | -| **Kestävyys** | Palveluntarjoajan profiilit, muokattavat nopeusrajoitukset, katkaisijan tila, käytännöt ja lukitut tunnisteet | -| **AI** | Ajatteleva budjettimäärittely, globaali järjestelmäkehote, nopea välimuistitilastot | -| **Lisäasetukset** | Yleiset välityspalvelimen asetukset (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Kustannukset ja budjetin hallinta +### Costs & Budget Management -Pääsy kohdasta **Käyttöpaneeli → Kulut**. +Access via **Dashboard → Costs**. -| Välilehti | Tarkoitus | -| --------------- | --------------------------------------------------------------------------------------------------------------- | -| **Budjetti** | Aseta kulutusrajat API-avaimelle päivä-/viikko-/kuukausibudjeteilla ja reaaliaikaisella seurannalla | -| **Hinnoittelu** | Tarkastele ja muokkaa mallin hinnoittelumerkintöjä – hinta per 1 000 syöttö-/tulostustunnusta toimittajaa kohti | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Kustannusten seuranta:** Jokainen pyyntö kirjaa tunnuksen käytön ja laskee kustannukset hinnoittelutaulukon avulla. Näytä erittelyt kohdassa **Käyttöpaneeli → Käyttö** tarjoajan, mallin ja API-avaimen mukaan. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Äänen transkriptio +### Audio Transcription -OmniRoute tukee äänen transkriptiota OpenAI-yhteensopivan päätepisteen kautta: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Saatavilla olevat palveluntarjoajat: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Tuetut äänimuodot: `mp3`, `wav`, `m4a`, `flac`, `ogg`, +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Yhdistelmätasapainotusstrategiat +### Combo Balancing Strategies -Määritä yhdistelmäkohtainen tasapainotus kohdassa **Käyttöpaneeli → Yhdistelmät → Luo/muokkaa → Strategia**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategia | Kuvaus | -| ---------------------- | ---------------------------------------------------------------------------------------- | -| **Round-Robin** | Pyörii mallien välillä peräkkäin | -| **Etusija** | Kokeilee aina ensimmäistä mallia; palautuu vain virheen yhteydessä | -| **Satunnainen** | Valitsee satunnaisen mallin yhdistelmästä jokaiselle pyynnölle | -| **Painotettu** | Reitit suhteellisesti mallikohtaisten painojen perusteella | -| **Vähiten käytetty** | Reitit malliin, jolla on vähiten viimeaikaisia ​​pyyntöjä (käyttää yhdistelmämittareita) | -| **Kustannusoptimoitu** | Reitit halvimpaan saatavilla olevaan malliin (käyttää hinnoittelutaulukkoa) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Yleiset yhdistelmäoletukset voidaan asettaa kohdassa **Kojelauta → Asetukset → Reititys → Yhdistelmäoletukset**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Terveyden hallintapaneeli +### Health Dashboard -Pääsy kohdasta **Dashboard → Health**. Reaaliaikainen järjestelmän kunnon yleiskatsaus 6 kortilla: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Kortti | Mitä se näyttää | -| --------------------------- | ------------------------------------------------------------------------------------ | -| **Järjestelmän tila** | Käyttöaika, versio, muistin käyttö, tietohakemisto | -| **Tarjoajan terveys** | Palveluntarjoajakohtainen katkaisijan tila (suljettu/auki/puoliauki) | -| **Rate Limits** | Aktiivisen nopeuden rajan viilennyksiä tiliä kohti jäljellä olevan ajan kanssa | -| **Aktiiviset lukitukset** | Palveluntarjoajat, jotka on tilapäisesti estetty lukituskäytännön vuoksi | -| **Allekirjoitusvälimuisti** | Päällekkäisyyden poistamisen välimuistitilastot (aktiiviset avaimet, osumaprosentti) | -| **Viiveen telemetria** | p50/p95/p99 latenssin yhteenlaskettu palveluntarjoajakohtainen | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Provinkki:** Terveys-sivu päivittyy automaattisesti 10 sekunnin välein. Käytä katkaisijakorttia tunnistaaksesi, millä palveluntarjoajilla on ongelmia. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/fr/API_REFERENCE.md b/docs/i18n/fr/API_REFERENCE.md index 4c935f1005..b795722c11 100644 --- a/docs/i18n/fr/API_REFERENCE.md +++ b/docs/i18n/fr/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Référence API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Référence complète pour tous les points de terminaison de l'API OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Table des matières +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Référence complète pour tous les points de terminaison de l'API OmniRoute. --- -## Fins de chat +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### En-têtes personnalisés +### Custom Headers -| En-tête | Itinéraire | Descriptif | -| ------------------------ | ---------- | ---------------------------------------------------- | -| `X-OmniRoute-No-Cache` | Demande | Défini sur `true` pour contourner le cache | -| `X-OmniRoute-Progress` | Demande | Défini sur `true` pour les événements de progression | -| `Idempotency-Key` | Demande | Clé de déduplication (fenêtre 5s) | -| `X-Request-Id` | Demande | Clé de déduplication alternative | -| `X-OmniRoute-Cache` | Réponse | `HIT` ou `MISS` (sans streaming) | -| `X-OmniRoute-Idempotent` | Réponse | `true` si dédupliqué | -| `X-OmniRoute-Progress` | Réponse | `enabled` si le suivi des progrès est activé | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Intégrations +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Fournisseurs disponibles : Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Génération d'images +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Fournisseurs disponibles : OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Liste des modèles +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Points de terminaison de compatibilité +## Compatibility Endpoints -| Méthode | Chemin | Formater | -| ------- | --------------------------- | -------------------------- | -| POSTER | `/v1/chat/completions` | OpenAI | -| POSTER | `/v1/messages` | Anthropique | -| POSTER | `/v1/responses` | Réponses OpenAI | -| POSTER | `/v1/embeddings` | OpenAI | -| POSTER | `/v1/images/generations` | OpenAI | -| OBTENIR | `/v1/models` | OpenAI | -| POSTER | `/v1/messages/count_tokens` | Anthropique | -| OBTENIR | `/v1beta/models` | Gémeaux | -| POSTER | `/v1beta/models/{...path}` | Gémeaux générer du contenu | -| POSTER | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Itinéraires de fournisseurs dédiés +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Le préfixe du fournisseur est ajouté automatiquement s'il est manquant. Les modèles incompatibles renvoient `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Cache sémantique +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Exemple de réponse : +Response example: ```json { @@ -162,154 +162,164 @@ Exemple de réponse : --- -## Tableau de bord et gestion +## Dashboard & Management -### Authentification +### Authentication -| Point de terminaison | Méthode | Descriptif | -| ----------------------------- | -------------- | ----------------------------- | -| `/api/auth/login` | POSTER | Connexion | -| `/api/auth/logout` | POSTER | Déconnexion | -| `/api/settings/require-login` | OBTENIR/METTRE | Basculer la connexion requise | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Gestion des fournisseurs +### Provider Management -| Point de terminaison | Méthode | Descriptif | -| ---------------------------- | ------------------------ | --------------------------------------- | -| `/api/providers` | OBTENIR/POST | Lister/créer des prestataires | -| `/api/providers/[id]` | OBTENIR/METTRE/SUPPRIMER | Gérer un fournisseur | -| `/api/providers/[id]/test` | POSTER | Connexion du fournisseur de test | -| `/api/providers/[id]/models` | OBTENIR | Liste des modèles de fournisseurs | -| `/api/providers/validate` | POSTER | Valider la configuration du fournisseur | -| `/api/provider-nodes*` | Divers | Gestion des nœuds de fournisseur | -| `/api/provider-models` | OBTENIR/POST/DELETE | Modèles personnalisés | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Flux OAuth +### OAuth Flows -| Point de terminaison | Méthode | Descriptif | -| -------------------------------- | ------- | ------------------------------- | -| `/api/oauth/[provider]/[action]` | Divers | OAuth spécifique au fournisseur | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Routage et configuration +### Routing & Config -| Point de terminaison | Méthode | Descriptif | -| --------------------- | ------------ | --------------------------------------- | -| `/api/models/alias` | OBTENIR/POST | Alias ​​du modèle | -| `/api/models/catalog` | OBTENIR | Tous les modèles par fournisseur + type | -| `/api/combos*` | Divers | Gestion des combos | -| `/api/keys*` | Divers | Gestion des clés API | -| `/api/pricing` | OBTENIR | Tarification du modèle | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Utilisation et analyses +### Usage & Analytics -| Point de terminaison | Méthode | Descriptif | -| --------------------------- | ------- | -------------------------------- | -| `/api/usage/history` | OBTENIR | Historique d'utilisation | -| `/api/usage/logs` | OBTENIR | Journaux d'utilisation | -| `/api/usage/request-logs` | OBTENIR | Journaux au niveau de la demande | -| `/api/usage/[connectionId]` | OBTENIR | Utilisation par connexion | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Paramètres +### Settings -| Point de terminaison | Méthode | Descriptif | -| ------------------------------- | -------------- | ---------------------------------------- | -| `/api/settings` | OBTENIR/METTRE | Paramètres généraux | -| `/api/settings/proxy` | OBTENIR/METTRE | Configuration du proxy réseau | -| `/api/settings/proxy/test` | POSTER | Tester la connexion proxy | -| `/api/settings/ip-filter` | OBTENIR/METTRE | Liste d'autorisation/liste de blocage IP | -| `/api/settings/thinking-budget` | OBTENIR/METTRE | Budget symbolique de raisonnement | -| `/api/settings/system-prompt` | OBTENIR/METTRE | Invite système globale | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Surveillance +### Monitoring -| Point de terminaison | Méthode | Descriptif | -| ------------------------ | ----------------- | ------------------------------- | -| `/api/sessions` | OBTENIR | Suivi de session active | -| `/api/rate-limits` | OBTENIR | Limites de taux par compte | -| `/api/monitoring/health` | OBTENIR | Bilan de santé | -| `/api/cache` | OBTENIR/SUPPRIMER | Statistiques du cache / effacer | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Sauvegarde et exportation/importation +### Backup & Export/Import -| Point de terminaison | Méthode | Descriptif | -| --------------------------- | ------- | ---------------------------------------------------------------- | -| `/api/db-backups` | OBTENIR | Liste des sauvegardes disponibles | -| `/api/db-backups` | METTRE | Créer une sauvegarde manuelle | -| `/api/db-backups` | POSTER | Restaurer à partir d'une sauvegarde spécifique | -| `/api/db-backups/export` | OBTENIR | Télécharger la base de données sous forme de fichier .sqlite | -| `/api/db-backups/import` | POSTER | Téléchargez le fichier .sqlite pour remplacer la base de données | -| `/api/db-backups/exportAll` | OBTENIR | Télécharger la sauvegarde complète sous forme d'archive .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Synchronisation avec le cloud +### Cloud Sync -| Point de terminaison | Méthode | Descriptif | -| ---------------------- | ------- | ----------------------------------- | -| `/api/sync/cloud` | Divers | Opérations de synchronisation cloud | -| `/api/sync/initialize` | POSTER | Initialiser la synchronisation | -| `/api/cloud/*` | Divers | Gestion du cloud | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Outils CLI +### CLI Tools -| Point de terminaison | Méthode | Descriptif | -| ---------------------------------- | ------- | -------------------------- | -| `/api/cli-tools/claude-settings` | OBTENIR | Statut CLI de Claude | -| `/api/cli-tools/codex-settings` | OBTENIR | Statut CLI du Codex | -| `/api/cli-tools/droid-settings` | OBTENIR | Statut de la CLI du droïde | -| `/api/cli-tools/openclaw-settings` | OBTENIR | Statut de la CLI OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | OBTENIR | Exécution CLI générique | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Les réponses CLI incluent : `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Résilience et limites de taux +### ACP Agents -| Point de terminaison | Méthode | Descriptif | -| ----------------------- | -------------- | ----------------------------------------------- | -| `/api/resilience` | OBTENIR/METTRE | Obtenir/mettre à jour les profils de résilience | -| `/api/resilience/reset` | POSTER | Réinitialiser les disjoncteurs | -| `/api/rate-limits` | OBTENIR | Statut de limite de débit par compte | -| `/api/rate-limit` | OBTENIR | Configuration de la limite de débit globale | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Évaluations +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Point de terminaison | Méthode | Descriptif | -| -------------------- | ------------ | --------------------------------------------------------- | -| `/api/evals` | OBTENIR/POST | Répertorier les suites d'évaluation/exécuter l'évaluation | +### Resilience & Rate Limits -### Politiques +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Point de terminaison | Méthode | Descriptif | -| -------------------- | ------------------- | ------------------------------- | -| `/api/policies` | OBTENIR/POST/DELETE | Gérer les politiques de routage | +### Evals -### Conformité +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Point de terminaison | Méthode | Descriptif | -| --------------------------- | ------- | ----------------------------------------- | -| `/api/compliance/audit-log` | OBTENIR | Journal d'audit de conformité (dernier N) | +### Policies -### v1beta (compatible Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Point de terminaison | Méthode | Descriptif | -| -------------------------- | ------- | --------------------------------------------- | -| `/v1beta/models` | OBTENIR | Liste des modèles au format Gemini | -| `/v1beta/models/{...path}` | POSTER | Point de terminaison Gemini `generateContent` | +### Compliance -Ces points de terminaison reflètent le format API de Gemini pour les clients qui attendent une compatibilité native avec le SDK Gemini. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### API internes/système +### v1beta (Gemini-Compatible) -| Point de terminaison | Méthode | Descriptif | -| -------------------- | ------- | ------------------------------------------------------------------------------------------ | -| `/api/init` | OBTENIR | Vérification de l'initialisation de l'application (utilisée lors de la première exécution) | -| `/api/tags` | OBTENIR | Balises de modèle compatibles Ollama (pour les clients Ollama) | -| `/api/restart` | POSTER | Déclencher un redémarrage progressif du serveur | -| `/api/shutdown` | POSTER | Déclencher l'arrêt progressif du serveur | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Remarque :** Ces points de terminaison sont utilisés en interne par le système ou pour la compatibilité du client Ollama. Ils ne sont généralement pas appelés par les utilisateurs finaux. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Transcription audio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transcrivez des fichiers audio à l'aide de Deepgram ou AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Demande :** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Réponse :** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Fournisseurs pris en charge :** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Formats pris en charge :** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Compatibilité Ollama +## Ollama Compatibility -Pour les clients qui utilisent le format API d'Ollama : +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Les demandes sont automatiquement traduites entre Ollama et les formats internes. +Requests are automatically translated between Ollama and internal formats. --- -## Télémétrie +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Réponse :** +**Response:** ```json { @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Disponibilité du modèle +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Traitement des demandes +## Request Processing -1. Le client envoie la demande à `/v1/*` -2. Le gestionnaire de route appelle `handleChat`, `handleEmbedding`, `handleAudioTranscription` ou `handleImageGeneration` -3. Le modèle est résolu (fournisseur/modèle direct ou alias/combo) -4. Informations d'identification sélectionnées dans la base de données locale avec filtrage de la disponibilité des comptes -5. Pour le chat : `handleChatCore` — détection de format, traduction, vérification du cache, vérification de l'idempotence -6. L'exécuteur du fournisseur envoie une requête en amont -7. Réponse traduite au format client (chat) ou renvoyée telle quelle (intégrations/images/audio) -8. Utilisation/journalisation enregistrée -9. Le repli s'applique aux erreurs selon les règles de combo +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Référence complète de l'architecture : [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Authentification +## Authentication -- Les itinéraires du tableau de bord (`/dashboard/*`) utilisent le cookie `auth_token` -- La connexion utilise le hachage du mot de passe enregistré ; retour à `INITIAL_PASSWORD` -- `requireLogin` basculable via `/api/settings/require-login` -- Les routes `/v1/*` nécessitent éventuellement une clé API Bearer lorsque `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/fr/ARCHITECTURE.md b/docs/i18n/fr/ARCHITECTURE.md index a8dab1d40f..258d62df53 100644 --- a/docs/i18n/fr/ARCHITECTURE.md +++ b/docs/i18n/fr/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Architecture OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Dernière mise à jour : 2026-02-18_ +_Last updated: 2026-03-04_ -## Résumé +## Executive Summary -OmniRoute est une passerelle de routage d'IA locale et un tableau de bord construit sur Next.js. -Il fournit un seul point de terminaison compatible OpenAI (`/v1/*`) et achemine le trafic vers plusieurs fournisseurs en amont avec traduction, secours, actualisation des jetons et suivi de l'utilisation. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Capacités de base : +Core capabilities: -- Surface API compatible OpenAI pour CLI/outils (28 fournisseurs) -- Traduction des requêtes/réponses dans tous les formats de fournisseurs -- Modèle de repli combo (séquence multi-modèles) -- Repli au niveau du compte (multi-comptes par fournisseur) -- Gestion des connexions du fournisseur de clé OAuth + API -- Génération d'embarquement via `/v1/embeddings` (6 fournisseurs, 9 modèles) -- Génération d'images via `/v1/images/generations` (4 fournisseurs, 9 modèles) -- Pensez à l'analyse des balises (`...`) pour les modèles de raisonnement -- Désinfection des réponses pour une compatibilité stricte avec le SDK OpenAI -- Normalisation des rôles (développeur → système, système → utilisateur) pour une compatibilité entre fournisseurs -- Conversion de sortie structurée (json_schema → Gemini ResponseSchema) -- Persistance locale pour les fournisseurs, les clés, les alias, les combos, les paramètres, les prix -- Suivi de l'utilisation/des coûts et journalisation des demandes -- Synchronisation cloud en option pour la synchronisation multi-appareils/états -- Liste d'autorisation/liste de blocage IP pour le contrôle d'accès aux API -- Penser la gestion budgétaire (passthrough/auto/custom/adaptatif) - -Injection rapide du système global -- Suivi de session et prise d'empreintes digitales -- Limitation de débit améliorée par compte avec des profils spécifiques au fournisseur -- Modèle de disjoncteur pour la résilience du fournisseur -- Protection de troupeau anti-tonnerre avec verrouillage mutex -- Cache de déduplication de requêtes basé sur les signatures -- Couche domaine : disponibilité du modèle, règles de coûts, politique de repli, politique de verrouillage -- Persistance de l'état du domaine (cache en écriture SQLite pour les solutions de repli, les budgets, les verrouillages, les disjoncteurs) -- Moteur de politique pour l'évaluation centralisée des demandes (verrouillage → budget → repli) -- Demande de télémétrie avec agrégation de latence p50/p95/p99 -- ID de corrélation (X-Request-Id) pour le traçage de bout en bout -- Journalisation d'audit de conformité avec désinscription par clé API -- Cadre d'évaluation pour l'assurance qualité LLM -- Tableau de bord de l'interface utilisateur de résilience avec l'état du disjoncteur en temps réel -- Fournisseurs OAuth modulaires (12 modules individuels sous `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Modèle d'exécution principal : +Primary runtime model: -- Les routes d'application Next.js sous `src/app/api/*` implémentent à la fois les API de tableau de bord et les API de compatibilité -- Un noyau SSE/routage partagé dans `src/sse/*` + `open-sse/*` gère l'exécution, la traduction, le streaming, le repli et l'utilisation du fournisseur. +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Portée et limites +## Scope and Boundaries -### Dans le champ d'application +### In Scope -- Runtime de la passerelle locale -- API de gestion des tableaux de bord -- Authentification du fournisseur et actualisation du jeton -- Demander une traduction et un streaming SSE -- État local + persistance d'utilisation -- Orchestration de synchronisation cloud en option +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Hors de portée +### Out of Scope -- Implémentation du service cloud derrière `NEXT_PUBLIC_CLOUD_URL` -- SLA/plan de contrôle du fournisseur en dehors du processus local -- Les binaires CLI externes eux-mêmes (Claude CLI, Codex CLI, etc.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Contexte système de haut niveau +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Composants d'exécution de base +## Core Runtime Components -## 1) API et couche de routage (routes de l'application Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Principaux répertoires : +Main directories: -- `src/app/api/v1/*` et `src/app/api/v1beta/*` pour les API de compatibilité -- `src/app/api/*` pour les API de gestion/configuration -- Les réécritures suivantes dans `next.config.mjs` mappent `/v1/*` à `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Itinéraires de compatibilité importants : +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — inclut des modèles personnalisés avec `custom: true` -- `src/app/api/v1/embeddings/route.ts` — génération d'intégration (6 fournisseurs) -- `src/app/api/v1/images/generations/route.ts` — génération d'images (4+ fournisseurs dont Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — chat dédié par fournisseur -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — intégrations dédiées par fournisseur -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — images dédiées par fournisseur +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Domaines de gestion : +Management domains: -- Authentification/paramètres : `src/app/api/auth/*`, `src/app/api/settings/*` -- Fournisseurs/connexions : `src/app/api/providers*` -- Nœuds fournisseurs : `src/app/api/provider-nodes*` -- Modèles personnalisés : `src/app/api/provider-models` (GET/POST/DELETE) -- Catalogue de modèles : `src/app/api/models/catalog` (GET) -- Configuration proxy : `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - -OAuth : `src/app/api/oauth/*` -- Clés/alias/combos/tarification : `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Utilisation : `src/app/api/usage/*` -- Synchronisation/cloud : `src/app/api/sync/*`, `src/app/api/cloud/*` -- Aides à l'outillage CLI : `src/app/api/cli-tools/*` -- Filtre IP : `src/app/api/settings/ip-filter` (GET/PUT) -- Budget de réflexion : `src/app/api/settings/thinking-budget` (GET/PUT) -- Invite système : `src/app/api/settings/system-prompt` (GET/PUT) -- Séances : `src/app/api/sessions` (GET) -- Limites de débit : `src/app/api/rate-limits` (GET) -- Résilience : `src/app/api/resilience` (GET/PATCH) — profils de fournisseur, disjoncteur, état limite de débit -- Réinitialisation de la résilience : `src/app/api/resilience/reset` (POST) – réinitialisation des disjoncteurs + temps de recharge -- Statistiques du cache : `src/app/api/cache/stats` (GET/DELETE) -- Disponibilité du modèle : `src/app/api/models/availability` (GET/POST) -- Télémétrie : `src/app/api/telemetry/summary` (GET) - -Budget : `src/app/api/usage/budget` (GET/POST) -- Chaînes de secours : `src/app/api/fallback/chains` (GET/POST/DELETE) -- Audit de conformité : `src/app/api/compliance/audit-log` (GET) -- Évaluations : `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Politiques : `src/app/api/policies` (GET/POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + noyau de traduction +## 2) SSE + Translation Core -Principaux modules de flux : +Main flow modules: -- Entrée : `src/sse/handlers/chat.ts` -- Orchestration de base : `open-sse/handlers/chatCore.ts` -- Adaptateurs d'exécution du fournisseur : `open-sse/executors/*` -- Détection de format/configuration du fournisseur : `open-sse/services/provider.ts` -- Analyse/résolution du modèle : `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Logique de repli du compte : `open-sse/services/accountFallback.ts` -- Registre de traduction : `open-sse/translator/index.ts` -- Transformations de flux : `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Extraction/normalisation d'utilisation : `open-sse/utils/usageTracking.ts` -- Pensez à l'analyseur de balises : `open-sse/utils/thinkTagParser.ts` -- Gestionnaire d'intégration : `open-sse/handlers/embeddings.ts` -- Registre des fournisseurs d'intégration : `open-sse/config/embeddingRegistry.ts` -- Gestionnaire de génération d'images : `open-sse/handlers/imageGeneration.ts` -- Registre du fournisseur d'images : `open-sse/config/imageRegistry.ts` -- Désinfection de la réponse : `open-sse/handlers/responseSanitizer.ts` -- Normalisation des rôles : `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Services (logique métier) : +Services (business logic): -- Sélection/notation du compte : `open-sse/services/accountSelector.ts` -- Gestion du cycle de vie du contexte : `open-sse/services/contextManager.ts` -- Application du filtre IP : `open-sse/services/ipFilter.ts` -- Suivi de session : `open-sse/services/sessionManager.ts` -- Demande de déduplication : `open-sse/services/signatureCache.ts` -- Injection rapide du système : `open-sse/services/systemPrompt.ts` -- Penser la gestion budgétaire : `open-sse/services/thinkingBudget.ts` -- Routage du modèle générique : `open-sse/services/wildcardRouter.ts` -- Gestion des limites de débit : `open-sse/services/rateLimitManager.ts` -- Disjoncteur : `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Modules de couche de domaine : +Domain layer modules: -- Disponibilité du modèle : `src/lib/domain/modelAvailability.ts` -- Règles de coûts/budgets : `src/lib/domain/costRules.ts` -- Politique de repli : `src/lib/domain/fallbackPolicy.ts` -- Résolveur combiné : `src/lib/domain/comboResolver.ts` -- Politique de verrouillage : `src/lib/domain/lockoutPolicy.ts` -- Moteur de politique : `src/domain/policyEngine.ts` — verrouillage centralisé → budget → évaluation de secours -- Catalogue de codes d'erreur : `src/lib/domain/errorCodes.ts` -- ID de la demande : `src/lib/domain/requestId.ts` -- Délai d'expiration de la récupération : `src/lib/domain/fetchTimeout.ts` -- Demande de télémétrie : `src/lib/domain/requestTelemetry.ts` -- Conformité/audit : `src/lib/domain/compliance/index.ts` -- Coureur d'évaluation : `src/lib/domain/evalRunner.ts` -- Persistance de l'état du domaine : `src/lib/db/domainState.ts` — SQLite CRUD pour les chaînes de secours, les budgets, l'historique des coûts, l'état de verrouillage, les disjoncteurs +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Modules du fournisseur OAuth (12 fichiers individuels sous `src/lib/oauth/providers/`) : +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Index du registre : `src/lib/oauth/providers/index.ts` -- Fournisseurs individuels : `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Wrapper mince : `src/lib/oauth/providers.ts` — réexportations à partir de modules individuels +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Couche de persistance +## 3) Persistence Layer -Base de données d'état primaire : +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- fichier : `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` lorsqu'il est défini, sinon `~/.omniroute/db.json`) -- entités : ProviderConnections, ProvideNodes, modelAliases, combos, apiKeys, paramètres, tarification, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Base de données d'utilisation : +Usage persistence: -- `src/lib/usageDb.ts` -- fichiers : `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- suit la même politique de répertoire de base que `localDb` (`DATA_DIR`, puis `XDG_CONFIG_HOME/omniroute` lorsqu'il est défini) -- décomposé en sous-modules ciblés : `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -Base de données d'état du domaine (SQLite) : +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — Opérations CRUD pour l'état du domaine -- Tables (créées dans `src/lib/db/core.ts`) : `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Modèle de cache en écriture : les cartes en mémoire font autorité au moment de l'exécution ; les mutations sont écrites de manière synchrone dans SQLite ; l'état est restauré à partir de la base de données lors d'un démarrage à froid +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Surfaces d'authentification + sécurité +## 4) Auth + Security Surfaces -- Authentification des cookies du tableau de bord : `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Génération/vérification de clé API : `src/shared/utils/apiKey.ts` -- Les secrets du fournisseur ont persisté dans les entrées `providerConnections` -- Prise en charge du proxy sortant via `open-sse/utils/proxyFetch.ts` (vars d'environnement) et `open-sse/utils/networkProxy.ts` (configurable par fournisseur ou global) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Synchronisation dans le cloud +## 5) Cloud Sync -- Initialisation du planificateur : `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Tâche périodique : `src/shared/services/cloudSyncScheduler.ts` -- Itinéraire de contrôle : `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Cycle de vie des demandes (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Flux de repli du compte +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Les décisions de secours sont pilotées par `open-sse/services/accountFallback.ts` à l'aide de codes d'état et d'heuristiques de messages d'erreur. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Cycle de vie de l'intégration OAuth et de l'actualisation des jetons +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -L'actualisation pendant le trafic en direct est exécutée dans `open-sse/handlers/chatCore.ts` via l'exécuteur `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Cycle de vie de Cloud Sync (Activer/Sync/Désactiver) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -La synchronisation périodique est déclenchée par `CloudSyncScheduler` lorsque le cloud est activé. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Modèle de données et carte de stockage +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Fichiers de stockage physique : +Physical storage files: -- état principal : `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` lorsqu'il est défini, sinon `~/.omniroute/db.json`) -- statistiques d'utilisation : `${DATA_DIR}/usage.json` -- lignes de journal de demande : `${DATA_DIR}/log.txt` -- sessions facultatives de débogage de traduction/demande : `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topologie de déploiement +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Cartographie des modules (critique en matière de décision) +## Module Mapping (Decision-Critical) -### Modules de routage et d'API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*` : API de compatibilité -- `src/app/api/v1/providers/[provider]/*` : routes dédiées par fournisseur (chat, intégrations, images) -- `src/app/api/providers*` : fournisseur CRUD, validation, tests -- `src/app/api/provider-nodes*` : gestion des nœuds compatibles personnalisés -- `src/app/api/provider-models` : gestion de modèles personnalisés (CRUD) -- `src/app/api/models/catalog` : API de catalogue de modèles complet (tous les types regroupés par fournisseur) -- `src/app/api/oauth/*` : flux OAuth/code de périphérique -- `src/app/api/keys*` : cycle de vie de la clé API locale -- `src/app/api/models/alias` : gestion des alias -- `src/app/api/combos*` : gestion des combos de repli -- `src/app/api/pricing` : remplacements de prix pour le calcul des coûts -- `src/app/api/settings/proxy` : configuration du proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test` : test de connectivité proxy sortant (POST) -- `src/app/api/usage/*` : API d'utilisation et de logs -- `src/app/api/sync/*` + `src/app/api/cloud/*` : synchronisation cloud et assistants orientés cloud -- `src/app/api/cli-tools/*` : rédacteurs/vérificateurs de configuration CLI locaux -- `src/app/api/settings/ip-filter` : liste autorisée/liste de blocage IP (GET/PUT) -- `src/app/api/settings/thinking-budget` : configuration du budget des jetons de réflexion (GET/PUT) -- `src/app/api/settings/system-prompt` : invite système globale (GET/PUT) -- `src/app/api/sessions` : listing des sessions actives (GET) -- `src/app/api/rate-limits` : statut de limite de débit par compte (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Noyau de routage et d'exécution +### Routing and Execution Core -- `src/sse/handlers/chat.ts` : analyse des requêtes, gestion des combos, boucle de sélection de compte -- `open-sse/handlers/chatCore.ts` : traduction, envoi de l'exécuteur, gestion des nouvelles tentatives/actualisations, configuration du flux -- `open-sse/executors/*` : comportement de réseau et de format spécifique au fournisseur +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Registre de traduction et convertisseurs de format +### Translation Registry and Format Converters -- `open-sse/translator/index.ts` : registre et orchestration des traducteurs -- Demander des traducteurs : `open-sse/translator/request/*` -- Traducteurs de réponse : `open-sse/translator/response/*` -- Constantes de format : `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Persistance +### Persistence -- `src/lib/localDb.ts` : configuration/état persistant -- `src/lib/usageDb.ts` : historique d'utilisation et journaux de requêtes glissantes +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Couverture de l'exécuteur du fournisseur (modèle de stratégie) +## Provider Executor Coverage (Strategy Pattern) -Chaque fournisseur dispose d'un exécuteur spécialisé étendant `BaseExecutor` (dans `open-sse/executors/base.ts`), qui fournit la création d'URL, la construction d'en-tête, les nouvelles tentatives avec interruption exponentielle, les points d'ancrage d'actualisation des informations d'identification et la méthode d'orchestration `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Exécuteur testamentaire | Fournisseur(s) | Manutention spéciale | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configuration dynamique d'URL/d'en-tête par fournisseur | -| `AntigravityExecutor` | Google Antigravité | ID de projet/session personnalisés, analyse réessayée après | -| `CodexExecutor` | Codex OpenAI | Injecte des instructions système, force un effort de raisonnement | -| `CursorExecutor` | Curseur IDE | Protocole ConnectRPC, encodage Protobuf, signature de demande via somme de contrôle | -| `GithubExecutor` | Copilote GitHub | Actualisation du jeton Copilot, en-têtes imitant VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Format binaire AWS EventStream → conversion SSE | -| `GeminiCLIExecutor` | CLI Gémeaux | Cycle d'actualisation du jeton Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Tous les autres fournisseurs (y compris les nœuds compatibles personnalisés) utilisent le `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matrice de compatibilité des fournisseurs +## Provider Compatibility Matrix -| Fournisseur | Formater | Authentification | Flux | Hors flux | Actualisation des jetons | API d'utilisation | -| --------------------- | ----------------- | ------------------------------- | ---------------- | --------- | ------------------------ | ---------------------------- | -| Claude | Claude | Clé API/OAuth | ✅ | ✅ | ✅ | ⚠️ Administrateur uniquement | -| Gémeaux | Gémeaux | Clé API/OAuth | ✅ | ✅ | ✅ | ⚠️Console Cloud | -| CLI Gémeaux | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️Console Cloud | -| Antigravité | antigravité | OAuth | ✅ | ✅ | ✅ | ✅ API de quota complet | -| OpenAI | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| Codex | réponses ouvertes | OAuth | ✅ forcé | ❌ | ✅ | ✅ Limites de taux | -| Copilote GitHub | ouvert | OAuth + Jeton Copilot | ✅ | ✅ | ✅ | ✅ Instantanés de quotas | -| Curseur | curseur | Somme de contrôle personnalisée | ✅ | ✅ | ❌ | ❌ | -| Kiro | Kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limites d'utilisation | -| Qwen | ouvert | OAuth | ✅ | ✅ | ✅ | ⚠️ Par demande | -| iFlow | ouvert | OAuth (de base) | ✅ | ✅ | ✅ | ⚠️ Par demande | -| OuvrirRouter | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | Claude | Clé API | ✅ | ✅ | ❌ | ❌ | -| Recherche profonde | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| Groq | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| Mistral | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| Perplexité | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| Ensemble IA | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| IA de feux d'artifice | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| Cérébraux | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| Cohérer | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | -| NIM NVIDIA | ouvert | Clé API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Format de couverture de traduction +## Format Translation Coverage -Les formats sources détectés incluent : +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Les formats cibles incluent : +Target formats include: -- Discussion/Réponses OpenAI - -Claude -- Enveloppe Gemini/Gemini-CLI/Antigravité - -Kiro -- Curseur +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -Les traductions utilisent **OpenAI comme format hub** — toutes les conversions passent par OpenAI comme intermédiaire : +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Les traductions sont sélectionnées dynamiquement en fonction de la forme de la charge utile source et du format cible du fournisseur. +Translations are selected dynamically based on source payload shape and provider target format. -Couches de traitement supplémentaires dans le pipeline de traduction : +Additional processing layers in the translation pipeline: -- **Désinfection des réponses** — Supprime les champs non standard des réponses au format OpenAI (à la fois en streaming et hors streaming) pour garantir une stricte conformité au SDK. -- **Normalisation des rôles** — Convertit `developer` → `system` pour les cibles non OpenAI ; fusionne `system` → `user` pour les modèles qui rejettent le rôle système (GLM, ERNIE) -- **Think tag extraction** — Analyse les blocs `...` du contenu dans le champ `reasoning_content` -- **Sortie structurée** — Convertit OpenAI `response_format.json_schema` en `responseMimeType` + `responseSchema` de Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Points de terminaison d'API pris en charge +## Supported API Endpoints -| Point de terminaison | Formater | Gestionnaire | -| -------------------------------------------------- | ------------------------ | ----------------------------------------------------------------- | -| `POST /v1/chat/completions` | Chat OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Messages de Claude | Même gestionnaire (détecté automatiquement) | -| `POST /v1/responses` | Réponses OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Intégrations OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Liste des modèles | Itinéraire API | -| `POST /v1/images/generations` | Images OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Liste des modèles | Itinéraire API | -| `POST /v1/providers/{provider}/chat/completions` | Chat OpenAI | Dédié par fournisseur avec validation du modèle | -| `POST /v1/providers/{provider}/embeddings` | Intégrations OpenAI | Dédié par fournisseur avec validation du modèle | -| `POST /v1/providers/{provider}/images/generations` | Images OpenAI | Dédié par fournisseur avec validation du modèle | -| `POST /v1/messages/count_tokens` | Compte de jetons Claude | Itinéraire API | -| `GET /v1/models` | Liste des modèles OpenAI | Route API (chat + intégration + image + modèles personnalisés) | -| `GET /api/models/catalog` | Catalogue | Tous les modèles regroupés par fournisseur + type | -| `POST /v1beta/models/*:streamGenerateContent` | Natif des Gémeaux | Itinéraire API | -| `GET/PUT/DELETE /api/settings/proxy` | Configuration du proxy | Configuration du proxy réseau | -| `POST /api/settings/proxy/test` | Connectivité proxy | Point de terminaison du test d’intégrité/de connectivité du proxy | -| `GET/POST/DELETE /api/provider-models` | Modèles personnalisés | Gestion de modèles personnalisés par fournisseur | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Gestionnaire de contournement +## Bypass Handler -Le gestionnaire de contournement (`open-sse/utils/bypassHandler.ts`) intercepte les requêtes « jetables » connues de Claude CLI (pings d'échauffement, extractions de titres et nombre de jetons) et renvoie une **fausse réponse** sans consommer de jetons du fournisseur en amont. Ceci est déclenché uniquement lorsque `User-Agent` contient `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Demander un pipeline d'enregistreur +## Request Logger Pipeline -L'enregistreur de requêtes (`open-sse/utils/requestLogger.ts`) fournit un pipeline de journalisation de débogage en 7 étapes, désactivé par défaut, activé via `ENABLE_REQUEST_LOGS=true` : +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Les fichiers sont écrits dans `/logs//` pour chaque session de demande. +Files are written to `/logs//` for each request session. -## Modes de défaillance et résilience +## Failure Modes and Resilience -## 1) Disponibilité du compte/fournisseur +## 1) Account/Provider Availability -- Temps de recharge du compte du fournisseur en cas d'erreurs transitoires/taux/auth. -- repli du compte avant l'échec de la demande -- repli du modèle combiné lorsque le chemin modèle/fournisseur actuel est épuisé +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Expiration du jeton +## 2) Token Expiry -- pré-vérification et actualisation avec nouvelle tentative pour les fournisseurs actualisables -- Nouvelle tentative 401/403 après tentative d'actualisation dans le chemin principal +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Sécurité des flux +## 3) Stream Safety -- contrôleur de flux prenant en charge la déconnexion -- flux de traduction avec vidage de fin de flux et gestion `[DONE]` -- repli de l'estimation de l'utilisation lorsque les métadonnées d'utilisation du fournisseur sont manquantes +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Dégradation de la synchronisation cloud +## 4) Cloud Sync Degradation -- des erreurs de synchronisation apparaissent mais l'exécution locale continue -- le planificateur a une logique capable de réessayer, mais l'exécution périodique appelle actuellement une synchronisation à tentative unique par défaut +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Intégrité des données +## 5) Data Integrity -- Migration/réparation de forme de base de données pour les clés manquantes -- protections de réinitialisation JSON corrompues pour localDb et usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Observabilité et signaux opérationnels +## Observability and Operational Signals -Sources de visibilité d'exécution : +Runtime visibility sources: -- Journaux de console de `src/sse/utils/logger.ts` -- agrégats d'utilisation par requête dans `usage.json` -- Journal d'état de la demande textuelle dans `log.txt` -- Journaux facultatifs de requêtes/traductions approfondies sous `logs/` lorsque `ENABLE_REQUEST_LOGS=true` -- points de terminaison d'utilisation du tableau de bord (`/api/usage/*`) pour la consommation de l'interface utilisateur +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Limites sensibles à la sécurité +## Security-Sensitive Boundaries -- Le secret JWT (`JWT_SECRET`) sécurise la vérification/signature des cookies de session du tableau de bord -- Le mot de passe initial de secours (`INITIAL_PASSWORD`, par défaut `123456`) doit être remplacé dans les déploiements réels -- Le secret de la clé API HMAC (`API_KEY_SECRET`) sécurise le format de clé API locale généré -- Les secrets du fournisseur (clés/jetons API) sont conservés dans la base de données locale et doivent être protégés au niveau du système de fichiers -- Les points de terminaison de synchronisation dans le cloud s'appuient sur l'authentification par clé API + la sémantique de l'identifiant de la machine +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Matrice d'environnement et d'exécution +## Environment and Runtime Matrix -Variables d'environnement activement utilisées par le code : +Environment variables actively used by code: -- Application/authentification : `JWT_SECRET`, `INITIAL_PASSWORD` -- Stockage : `DATA_DIR` -- Comportement du nœud compatible : `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Remplacement facultatif de la base de stockage (Linux/macOS lorsque `DATA_DIR` n'est pas défini) : `XDG_CONFIG_HOME` -- Hachage de sécurité : `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Journalisation : `ENABLE_REQUEST_LOGS` -- URL de synchronisation/cloud : `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Proxy sortant : `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` et variantes minuscules -- Indicateurs de fonctionnalité SOCKS5 : `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Aides de plate-forme/d'exécution (pas de configuration spécifique à l'application) : `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Notes architecturales connues +## Known Architectural Notes -1. `usageDb` et `localDb` partagent désormais la même stratégie de répertoire de base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) avec la migration des fichiers existants. -2. `/api/v1/route.ts` renvoie une liste de modèles statiques et n'est pas la source principale de modèles utilisée par `/v1/models`. -3. L'enregistreur de requêtes écrit les en-têtes/corps complets lorsqu'il est activé ; traiter le répertoire des journaux comme sensible. -4. Le comportement du cloud dépend de l'exactitude du `NEXT_PUBLIC_BASE_URL` et de l'accessibilité du point de terminaison du cloud. -5. Le répertoire `open-sse/` est publié en tant que `@omniroute/open-sse` **package d'espace de travail npm**. Le code source l'importe via `@omniroute/open-sse/...` (résolu par Next.js `transpilePackages`). Les chemins de fichiers dans ce document utilisent toujours le nom de répertoire `open-sse/` par souci de cohérence. -6. Les graphiques du tableau de bord utilisent **Recharts** (basé sur SVG) pour des visualisations analytiques accessibles et interactives (graphiques à barres d'utilisation du modèle, tableaux de répartition des fournisseurs avec taux de réussite). -7. Les tests E2E utilisent **Playwright** (`tests/e2e/`), exécutés via `npm run test:e2e`. Les tests unitaires utilisent **l'exécuteur de test Node.js** (`tests/unit/`), exécutés via `npm run test:plan3`. Le code source sous `src/` est **TypeScript** (`.ts`/`.tsx`) ; l'espace de travail `open-sse/` reste JavaScript (`.js`). -8. La page Paramètres est organisée en 5 onglets : Sécurité, Routage (6 stratégies globales : remplissage en premier, round-robin, p2c, aléatoire, moins utilisé, coût optimisé), Résilience (limites de débit modifiables, disjoncteur, politiques), IA (budget de réflexion, invite système, cache d'invite), Avancé (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Liste de contrôle de vérification opérationnelle +## Operational Verification Checklist -- Construire à partir des sources : `npm run build` -- Créer une image Docker : `docker build -t omniroute .` -- Démarrez le service et vérifiez : +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- L'URL de base cible CLI doit être `http://:20128/v1` lorsque `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/fr/CODEBASE_DOCUMENTATION.md b/docs/i18n/fr/CODEBASE_DOCUMENTATION.md index d4b6366d6a..303880c198 100644 --- a/docs/i18n/fr/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/fr/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Documentation de base de code +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Un guide complet et convivial pour les débutants sur le routeur proxy IA multifournisseur **omniroute**. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Qu'est-ce qu'omniroute ? +## 1. What Is omniroute? -omniroute est un **routeur proxy** qui se situe entre les clients IA (Claude CLI, Codex, Cursor IDE, etc.) et les fournisseurs d'IA (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Cela résout un gros problème : +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Différents clients d'IA parlent différentes « langues » (formats API), et différents fournisseurs d'IA s'attendent également à des « langues » différentes.** omniroute traduit automatiquement entre eux. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Considérez-le comme un traducteur universel aux Nations Unies : n'importe quel délégué peut parler n'importe quelle langue, et le traducteur la convertit pour n'importe quel autre délégué. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Présentation de l'architecture +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Principe de base : traduction en étoile +### Core Principle: Hub-and-Spoke Translation -Toutes les traductions de format passent par le **format OpenAI comme hub** : +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Cela signifie que vous n'avez besoin que de **N traducteurs** (un par format) au lieu de **N²** (chaque paire). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Structure du projet +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Répartition module par module +## 4. Module-by-Module Breakdown -### 4.1 Configuration (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -La **source unique de vérité** pour toutes les configurations de fournisseurs. +The **single source of truth** for all provider configuration. -| Fichier | Objectif | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | Objet `PROVIDERS` avec les URL de base, les informations d'identification OAuth (par défaut), les en-têtes et les invites système par défaut pour chaque fournisseur. Définit également `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` et `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Charge les informations d'identification externes de `data/provider-credentials.json` et les fusionne avec les valeurs par défaut codées en dur dans `PROVIDERS`. Garde les secrets hors du contrôle des sources tout en conservant la compatibilité ascendante. | -| `providerModels.ts` | Registre central des modèles : mappe les alias des fournisseurs → les ID de modèle. Fonctionne comme `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Instructions système injectées dans les requêtes Codex (contraintes d'édition, règles sandbox, politiques d'approbation). | -| `defaultThinkingSignature.ts` | Signatures « pensées » par défaut pour les modèles Claude et Gemini. | -| `ollamaModels.ts` | Définition de schéma pour les modèles Ollama locaux (nom, taille, famille, quantification). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Flux de chargement des informations d'identification +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Exécuteurs (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Les exécuteurs encapsulent la **logique spécifique au fournisseur** à l'aide du **Modèle de stratégie**. Chaque exécuteur remplace les méthodes de base selon les besoins. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Exécuteur testamentaire | Fournisseur | Spécialisations clés | -| ----------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `base.ts` | — | Base abstraite : création d'URL, en-têtes, logique de nouvelle tentative, actualisation des informations d'identification | -| `default.ts` | Claude, Gémeaux, OpenAI, GLM, Kimi, MiniMax | Actualisation du jeton OAuth générique pour les fournisseurs standards | -| `antigravity.ts` | Code Google Cloud | Génération d'ID de projet/session, secours multi-URL, nouvelle tentative d'analyse personnalisée à partir des messages d'erreur ("réinitialisation après 2h7m23s") | -| `cursor.ts` | Curseur IDE | **Le plus complexe** : authentification par somme de contrôle SHA-256, encodage de requête Protobuf, EventStream binaire → analyse de réponse SSE | -| `codex.ts` | Codex OpenAI | Injecte les instructions système, gère les niveaux de réflexion, supprime les paramètres non pris en charge | -| `gemini-cli.ts` | CLI Google Gemini | Création d'URL personnalisées (`streamGenerateContent`), actualisation du jeton Google OAuth | -| `github.ts` | Copilote GitHub | Système à double jeton (GitHub OAuth + jeton Copilot), imitation d'en-tête VSCode | -| `kiro.ts` | AWS CodeWhisperer | Analyse binaire AWS EventStream, cadres d'événements AMZN, estimation de jetons | -| `index.ts` | — | Factory : nom du fournisseur de cartes → classe d'exécuteur, avec solution de secours par défaut | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Gestionnaires (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -La **couche d'orchestration** : coordonne la traduction, l'exécution, le streaming et la gestion des erreurs. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Fichier | Objectif | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Orchestrateur central** (~600 lignes). Gère le cycle de vie complet de la demande : détection du format → traduction → répartition de l'exécuteur → réponse en streaming/non-streaming → actualisation du jeton → gestion des erreurs → journalisation de l'utilisation. | -| `responsesHandler.ts` | Adaptateur pour l'API Responses d'OpenAI : convertit le format des réponses → Fins de discussion → envoie à `chatCore` → reconvertit SSE au format de réponses. | -| `embeddings.ts` | Gestionnaire de génération d'intégration : résout le modèle d'intégration → fournisseur, envoi à l'API du fournisseur, renvoie la réponse d'intégration compatible OpenAI. Prend en charge plus de 6 fournisseurs. | -| `imageGeneration.ts` | Gestionnaire de génération d'images : résout le modèle d'image → fournisseur, prend en charge les modes compatibles OpenAI, Gemini-image (Antigravity) et de secours (Nebius). Renvoie des images base64 ou URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Cycle de vie des requêtes (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -260,26 +260,26 @@ sequenceDiagram ### 4.4 Services (`open-sse/services/`) -Logique métier qui prend en charge les gestionnaires et les exécuteurs. +Business logic that supports the handlers and executors. -| Fichier | Objectif | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Détection de format** (`detectFormat`) : analyse la structure du corps de la requête pour identifier les formats Claude/OpenAI/Gemini/Antigravity/Responses (inclut l'heuristique `max_tokens` pour Claude). Aussi : création d'URL, création d'en-têtes, réflexion sur la normalisation de la configuration. Prend en charge les fournisseurs dynamiques `openai-compatible-*` et `anthropic-compatible-*`. | -| `model.ts` | Analyse de chaîne de modèle (`claude/model-name` → `{provider: "claude", model: "model-name"}`), résolution d'alias avec détection de collision, désinfection des entrées (rejette les caractères de parcours/contrôle de chemin) et résolution d'informations de modèle avec prise en charge du getter d'alias asynchrone. | -| `accountFallback.ts` | Gestion des limites de débit : interruption exponentielle (1s → 2s → 4s → max 2min), gestion du temps de recharge du compte, classification des erreurs (quelles erreurs déclenchent le repli ou non). | -| `tokenRefresh.ts` | Actualisation du jeton OAuth pour **chaque fournisseur** : Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (double jeton OAuth + Copilot), Kiro (AWS SSO OIDC + Social Auth). Inclut un cache de déduplication de promesses en cours et une nouvelle tentative avec une interruption exponentielle. | -| `combo.ts` | **Modèles combo** : chaînes de modèles de secours. Si le modèle A échoue avec une erreur éligible au repli, essayez le modèle B, puis C, etc. Renvoie les codes d'état en amont réels. | -| `usage.ts` | Récupère les données de quota/utilisation des API du fournisseur (quotas GitHub Copilot, quotas du modèle Antigravity, limites de débit du Codex, répartitions d'utilisation de Kiro, paramètres Claude). | -| `accountSelector.ts` | Sélection intelligente des comptes avec algorithme de notation : prend en compte la priorité, l'état de santé, la position du tourniquet et l'état du temps de recharge pour choisir le compte optimal pour chaque demande. | -| `contextManager.ts` | Gestion du cycle de vie du contexte de demande : crée et suit des objets de contexte par demande avec des métadonnées (ID de demande, horodatages, informations sur le fournisseur) pour le débogage et la journalisation. | -| `ipFilter.ts` | Contrôle d'accès basé sur IP : prend en charge les modes liste d'autorisation et liste de blocage. Valide l'adresse IP du client par rapport aux règles configurées avant de traiter les requêtes API. | -| `sessionManager.ts` | Suivi des sessions avec empreintes digitales des clients : suit les sessions actives à l'aide d'identifiants client hachés, surveille le nombre de demandes et fournit des métriques de session. | -| `signatureCache.ts` | Cache de déduplication basé sur les signatures de requête : évite les requêtes en double en mettant en cache les signatures de requêtes récentes et en renvoyant les réponses mises en cache pour les requêtes identiques dans une fenêtre de temps. | -| `systemPrompt.ts` | Injection d’invite système globale : ajoute ou ajoute une invite système configurable à toutes les requêtes, avec gestion de la compatibilité par fournisseur. | -| `thinkingBudget.ts` | Gestion du budget des jetons de raisonnement : prend en charge les modes passthrough, automatique (configuration de réflexion en bande), personnalisé (budget fixe) et adaptatif (à l'échelle de la complexité) pour contrôler les jetons de réflexion/raisonnement. | -| `wildcardRouter.ts` | Routage de modèles de modèles génériques : résout les modèles de caractères génériques (par exemple, `*/claude-*`) en paires fournisseur/modèle concrètes en fonction de la disponibilité et de la priorité. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Déduplication d'actualisation des jetons +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Machine d'état de secours du compte +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Chaîne de modèles combo +#### Combo Model Chain ```mermaid flowchart LR @@ -344,9 +344,9 @@ flowchart LR --- -### 4.5 Traducteur (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -Le **moteur de traduction de format** utilisant un système de plugin d'auto-enregistrement. +The **format translation engine** using a self-registering plugin system. #### Architecture @@ -374,15 +374,15 @@ graph TD end ``` -| Annuaire | Fichiers | Descriptif | -| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 traducteurs | Convertissez les corps de requête entre les formats. Chaque fichier s'auto-enregistre via `register(from, to, fn)` lors de l'importation. | -| `response/` | 7 traducteurs | Convertissez les morceaux de réponse en streaming entre les formats. Gère les types d’événements SSE, les blocs de réflexion et les appels d’outils. | -| `helpers/` | 6 aides | Utilitaires partagés : `claudeHelper` (extraction d'invite système, configuration de réflexion), `geminiHelper` (mapping parties/contenu), `openaiHelper` (filtrage de format), `toolCallHelper` (génération d'ID, injection de réponse manquante), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Moteur de traduction : `translateRequest()`, `translateResponse()`, gestion des états, registre. | -| `formats.ts` | — | Constantes de format : `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Conception des clés : plugins à enregistrement automatique +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Utilitaires (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Fichier | Objectif | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Création de réponses aux erreurs (format compatible OpenAI), analyse des erreurs en amont, extraction du temps de nouvelle tentative Antigravity à partir des messages d'erreur, streaming d'erreurs SSE. | -| `stream.ts` | **SSE Transform Stream** : le pipeline de streaming principal. Deux modes : `TRANSLATE` (traduction plein format) et `PASSTHROUGH` (normaliser + extraire l'utilisation). Gère la mise en mémoire tampon des blocs, l'estimation de l'utilisation et le suivi de la longueur du contenu. Les instances d'encodeur/décodeur par flux évitent l'état partagé. | -| `streamHelpers.ts` | Utilitaires SSE de bas niveau : `parseSSELine` (tolérant les espaces), `hasValuableContent` (filtre les morceaux vides pour OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (sérialisation SSE sensible au format avec nettoyage `perf_metrics`). | -| `usageTracking.ts` | Extraction de l'utilisation des jetons à partir de n'importe quel format (Claude/OpenAI/Gemini/Responses), estimation avec des ratios outil/message séparés par jeton, ajout de tampon (marge de sécurité de 2000 jetons), filtrage de champs spécifiques au format, journalisation de la console avec couleurs ANSI. | -| `requestLogger.ts` | Journalisation des demandes basées sur des fichiers (opt-in via `ENABLE_REQUEST_LOGS=true`). Crée des dossiers de session avec des fichiers numérotés : `1_req_client.json` → `7_res_client.txt`. Toutes les E/S sont asynchrones (tirer et oublier). Masque les en-têtes sensibles. | -| `bypassHandler.ts` | Intercepte les modèles spécifiques de Claude CLI (extraction de titre, échauffement, décompte) et renvoie de fausses réponses sans appeler aucun fournisseur. Prend en charge le streaming et le non-streaming. Intentionnellement limité à la portée Claude CLI. | -| `networkProxy.ts` | Résout l'URL du proxy sortant pour un fournisseur donné avec la priorité : configuration spécifique au fournisseur → configuration globale → variables d'environnement (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Prend en charge les exclusions `NO_PROXY`. Met en cache la configuration pendant 30 s. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Pipeline de diffusion SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Structure de la session de l'enregistreur de requêtes +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Couche d'application (`src/`) +### 4.7 Application Layer (`src/`) -| Annuaire | Objectif | -| ------------- | ----------------------------------------------------------------------------------------------------- | -| `src/app/` | Interface utilisateur Web, routes API, middleware express, gestionnaires de rappel OAuth | -| `src/lib/` | Accès à la base de données (`localDb.ts`, `usageDb.ts`), authentification, partagé | -| `src/mitm/` | Utilitaires proxy Man-in-the-middle pour intercepter le trafic des fournisseurs | -| `src/models/` | Définitions du modèle de base de données | -| `src/shared/` | Wrappers autour des fonctions open-sse (fournisseur, flux, erreur, etc.) | -| `src/sse/` | Gestionnaires de points de terminaison SSE qui connectent la bibliothèque open-sse aux routes Express | -| `src/store/` | Gestion de l'état des applications | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Routes API notables +#### Notable API Routes -| Itinéraire | Méthodes | Objectif | -| --------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | OBTENIR/POST/DELETE | CRUD pour les modèles personnalisés par fournisseur | -| `/api/models/catalog` | OBTENIR | Catalogue agrégé de tous les modèles (chat, intégration, image, personnalisé) regroupés par fournisseur | -| `/api/settings/proxy` | OBTENIR/METTRE/SUPPRIMER | Configuration du proxy sortant hiérarchique (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POSTER | Valide la connectivité proxy et renvoie l'adresse IP/latence publique | -| `/v1/providers/[provider]/chat/completions` | POSTER | Compléments de chat dédiés par fournisseur avec validation du modèle | -| `/v1/providers/[provider]/embeddings` | POSTER | Intégrations dédiées par fournisseur avec validation du modèle | -| `/v1/providers/[provider]/images/generations` | POSTER | Génération d'images dédiée par fournisseur avec validation du modèle | -| `/api/settings/ip-filter` | OBTENIR/METTRE | Gestion des listes autorisées/bloquées IP | -| `/api/settings/thinking-budget` | OBTENIR/METTRE | Configuration du budget du jeton de raisonnement (passthrough/auto/custom/adaptatif) | -| `/api/settings/system-prompt` | OBTENIR/METTRE | Injection rapide du système global pour toutes les demandes | -| `/api/sessions` | OBTENIR | Suivi et métriques des sessions actives | -| `/api/rate-limits` | OBTENIR | Statut de limite de débit par compte | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Modèles de conception clés +## 5. Key Design Patterns -### 5.1 Traduction en étoile +### 5.1 Hub-and-Spoke Translation -Tous les formats sont traduits via le **format OpenAI comme hub**. L'ajout d'un nouveau fournisseur ne nécessite que l'écriture d'**une paire** de traducteurs (vers/depuis OpenAI), et non de N paires. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Modèle de stratégie de l'exécuteur +### 5.2 Executor Strategy Pattern -Chaque fournisseur dispose d'une classe d'exécuteur dédiée héritant de `BaseExecutor`. L'usine dans `executors/index.ts` sélectionne la bonne au moment de l'exécution. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Système de plugin d'auto-enregistrement +### 5.3 Self-Registering Plugin System -Les modules de traduction s'enregistrent eux-mêmes lors de l'importation via `register()`. Ajouter un nouveau traducteur consiste simplement à créer un fichier et à l'importer. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Repli de compte avec intervalle exponentiel +### 5.4 Account Fallback with Exponential Backoff -Lorsqu'un fournisseur renvoie 429/401/500, le système peut passer au compte suivant, en appliquant des temps de recharge exponentiels (1s → 2s → 4s → max 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Chaînes de modèles combinés +### 5.5 Combo Model Chains -Un "combo" regroupe plusieurs chaînes `provider/model`. Si le premier échoue, revenez automatiquement au suivant. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Traduction en continu avec état +### 5.6 Stateful Streaming Translation -La traduction des réponses maintient l'état dans les morceaux SSE (suivi des blocs de réflexion, accumulation d'appels d'outils, indexation des blocs de contenu) via le mécanisme `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Tampon de sécurité d'utilisation +### 5.7 Usage Safety Buffer -Un tampon de 2 000 jetons est ajouté à l'utilisation signalée pour empêcher les clients d'atteindre les limites de la fenêtre contextuelle en raison de la surcharge des invites système et de la traduction du format. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Formats pris en charge +## 6. Supported Formats -| Formater | Itinéraire | Identifiant | -| -------------------------- | ---------------- | ------------------ | -| Achèvements du chat OpenAI | source + cible | `openai` | -| API de réponses OpenAI | source + cible | `openai-responses` | -| Claude Anthropique | source + cible | `claude` | -| Google Gémeaux | source + cible | `gemini` | -| CLI Google Gemini | cible uniquement | `gemini-cli` | -| Antigravité | source + cible | `antigravity` | -| AWSKiro | cible uniquement | `kiro` | -| Curseur | cible uniquement | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Fournisseurs pris en charge +## 7. Supported Providers -| Fournisseur | Méthode d'authentification | Exécuteur testamentaire | Notes clés | -| ------------------------ | ---------------------------------------- | ----------------------- | ------------------------------------------------------------------------- | -| Claude Anthropique | Clé API ou OAuth | Par défaut | Utilise l'en-tête `x-api-key` | -| Google Gémeaux | Clé API ou OAuth | Par défaut | Utilise l'en-tête `x-goog-api-key` | -| CLI Google Gemini | OAuth | GémeauxCLI | Utilise le point de terminaison `streamGenerateContent` | -| Antigravité | OAuth | Antigravité | Solution de secours multi-URL, nouvelle tentative d'analyse personnalisée | -| OpenAI | Clé API | Par défaut | Authentification du porte-étendard | -| Codex | OAuth | Codex | Injecte les instructions système, gère la réflexion | -| Copilote GitHub | OAuth + jeton Copilot | GitHub | Double jeton, en-tête VSCode imitant | -| Kiro (AWS) | AWS SSO OIDC ou Social | Kiro | Analyse binaire d'EventStream | -| Curseur IDE | Authentification de la somme de contrôle | Curseur | Encodage Protobuf, sommes de contrôle SHA-256 | -| Qwen | OAuth | Par défaut | Authentification standard | -| iFlow | OAuth (Basique + Porteur) | Par défaut | En-tête à double authentification | -| OuvrirRouter | Clé API | Par défaut | Authentification du porte-étendard | -| GLM, Kimi, MiniMax | Clé API | Par défaut | Compatible Claude, utilisez `x-api-key` | -| `openai-compatible-*` | Clé API | Par défaut | Dynamique : tout point de terminaison compatible OpenAI | -| `anthropic-compatible-*` | Clé API | Par défaut | Dynamique : tout point de terminaison compatible Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Résumé du flux de données +## 8. Data Flow Summary -### Demande de diffusion en continu +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Demande sans streaming +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Flux de contournement (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/fr/FEATURES.md b/docs/i18n/fr/FEATURES.md index b098d4ed08..82cc73b67b 100644 --- a/docs/i18n/fr/FEATURES.md +++ b/docs/i18n/fr/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Galerie des fonctionnalités du tableau de bord +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Guide visuel de chaque section du tableau de bord OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Fournisseurs +## 🔌 Providers -Gérez les connexions des fournisseurs d'IA : fournisseurs OAuth (Claude Code, Codex, Gemini CLI), fournisseurs de clés API (Groq, DeepSeek, OpenRouter) et fournisseurs gratuits (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨Combinaisons +## 🎨 Combos -Créez des combinaisons de routage de modèles avec 6 stratégies : remplissage en premier, round-robin, puissance de deux choix, aléatoire, moins utilisé et coût optimisé. Chaque combo enchaîne plusieurs modèles avec un repli automatique. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Analyses +## 📊 Analytics -Analyses d'utilisation complètes avec consommation de jetons, estimations de coûts, cartes thermiques d'activité, graphiques de distribution hebdomadaire et répartitions par fournisseur. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Santé du système +## 🏥 System Health -Surveillance en temps réel : disponibilité, mémoire, version, centiles de latence (p50/p95/p99), statistiques du cache et états des disjoncteurs du fournisseur. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Terrain de jeu des traducteurs +## 🔧 Translator Playground -Quatre modes de débogage des traductions d'API : **Playground** (convertisseur de format), **Chat Tester** (requêtes en direct), **Test Bench** (tests par lots) et **Live Monitor** (flux en temps réel). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Paramètres +## 🎮 Model Playground _(v2.0.9+)_ -Paramètres généraux, stockage système, gestion des sauvegardes (base de données d'exportation/importation), apparence (mode sombre/clair), sécurité (inclut la protection des points de terminaison API et le blocage des fournisseurs personnalisés), le routage, la résilience et la configuration avancée. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Outils CLI +## 🔧 CLI Tools -Configuration en un clic pour les outils de codage d'IA : Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code et Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Demander des journaux +## 🤖 CLI Agents _(v2.0.11+)_ -Journalisation des demandes en temps réel avec filtrage par fournisseur, modèle, compte et clé API. Affiche les codes d'état, l'utilisation des jetons, la latence et les détails de la réponse. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Point de terminaison de l'API +## 🌐 API Endpoint -Votre point de terminaison d'API unifié avec répartition des capacités : achèvements de chat, intégrations, génération d'images, reclassement, transcription audio et clés API enregistrées. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/fr/TROUBLESHOOTING.md b/docs/i18n/fr/TROUBLESHOOTING.md index 980d8f9508..120092d63c 100644 --- a/docs/i18n/fr/TROUBLESHOOTING.md +++ b/docs/i18n/fr/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Dépannage +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Problèmes courants et solutions pour OmniRoute. +Common problems and solutions for OmniRoute. --- -## Corrections rapides +## Quick Fixes -| Problème | Solutions | -| ---------------------------------------------- | -------------------------------------------------------------------------------------- | -| La première connexion ne fonctionne pas | Vérifiez `INITIAL_PASSWORD` dans `.env` (par défaut : `123456`) | -| Le tableau de bord s'ouvre sur le mauvais port | Définir `PORT=20128` et `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Aucun journal de requête sous `logs/` | Définir `ENABLE_REQUEST_LOGS=true` | -| EACCES : autorisation refusée | Définissez `DATA_DIR=/path/to/writable/dir` pour remplacer `~/.omniroute` | -| La stratégie de routage ne sauvegarde pas | Mise à jour vers v1.4.11+ (correctif du schéma Zod pour la persistance des paramètres) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Problèmes de fournisseur +## Provider Issues -### "Le modèle linguistique n'a pas fourni de messages" +### "Language model did not provide messages" -**Cause :** Quota de fournisseur épuisé. +**Cause:** Provider quota exhausted. -**Correction :** +**Fix:** -1. Vérifiez le suivi des quotas du tableau de bord -2. Utilisez un combo avec des niveaux de secours -3. Passez au niveau moins cher/gratuit +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Limitation du débit +### Rate Limiting -**Cause :** Quota d'abonnement épuisé. +**Cause:** Subscription quota exhausted. -**Correction :** +**Fix:** -- Ajouter une solution de secours : `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Utilisez GLM/MiniMax comme sauvegarde bon marché +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Jeton OAuth expiré +### OAuth Token Expired -OmniRoute actualise automatiquement les jetons. Si les problèmes persistent : +OmniRoute auto-refreshes tokens. If issues persist: -1. Tableau de bord → Fournisseur → Reconnecter -2. Supprimez et rajoutez la connexion du fournisseur +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Problèmes liés au cloud +## Cloud Issues -### Erreurs de synchronisation dans le cloud +### Cloud Sync Errors -1. Vérifiez que `BASE_URL` pointe vers votre instance en cours d'exécution (par exemple, `http://localhost:20128`) -2. Vérifiez que `CLOUD_URL` pointe vers votre point de terminaison cloud (par exemple, `https://omniroute.dev`) -3. Gardez les valeurs `NEXT_PUBLIC_*` alignées avec les valeurs côté serveur +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` renvoie 500 +### Cloud `stream=false` Returns 500 -**Symptôme :** `Unexpected token 'd'...` sur le point de terminaison cloud pour les appels sans streaming. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Cause :** Upstream renvoie la charge utile SSE alors que le client attend du JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Solution :** Utilisez `stream=true` pour les appels directs vers le cloud. Le runtime local inclut le repli SSE → JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud indique Connecté mais "Clé API non valide" +### Cloud Says Connected but "Invalid API key" -1. Créez une nouvelle clé à partir du tableau de bord local (`/api/keys`) -2. Exécutez la synchronisation cloud : Activer le cloud → Synchroniser maintenant -3. Les clés anciennes/non synchronisées peuvent toujours renvoyer `401` sur le cloud +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Problèmes avec Docker +## Docker Issues -### L'outil CLI indique qu'il n'est pas installé +### CLI Tool Shows Not Installed -1. Vérifiez les champs d'exécution : `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Pour le mode portable : utilisez la cible d'image `runner-cli` (CLI fournies) -3. Pour le mode de montage de l'hôte : définissez `CLI_EXTRA_PATHS` et montez le répertoire bin de l'hôte en lecture seule. -4. Si `installed=true` et `runnable=false` : le binaire a été trouvé mais le contrôle de santé a échoué +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Validation rapide de l'exécution +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Problèmes de coûts +## Cost Issues -### Coûts élevés +### High Costs -1. Vérifiez les statistiques d'utilisation dans le tableau de bord → Utilisation -2. Basculez le modèle principal vers GLM/MiniMax -3. Utilisez l'offre gratuite (Gemini CLI, iFlow) pour les tâches non critiques -4. Définissez les budgets de coûts par clé API : Tableau de bord → Clés API → Budget +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Débogage +## Debugging -### Activer les journaux de requêtes +### Enable Request Logs -Définissez `ENABLE_REQUEST_LOGS=true` dans votre fichier `.env`. Les journaux apparaissent sous le répertoire `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Vérifier l'état du fournisseur +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Stockage d'exécution +### Runtime Storage -- État principal : `${DATA_DIR}/db.json` (fournisseurs, combos, alias, clés, paramètres) -- Utilisation : `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Journaux de demande : `/logs/...` (quand `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Problèmes de disjoncteur +## Circuit Breaker Issues -### Fournisseur bloqué à l'état OUVERT +### Provider stuck in OPEN state -Lorsque le disjoncteur d'un fournisseur est OUVERT, les demandes sont bloquées jusqu'à l'expiration du temps de recharge. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Correction :** +**Fix:** -1. Accédez à **Tableau de bord → Paramètres → Résilience** -2. Vérifiez la carte de disjoncteur du fournisseur concerné -3. Cliquez sur **Réinitialiser tout** pour effacer tous les disjoncteurs ou attendez l'expiration du temps de recharge. -4. Vérifiez que le fournisseur est réellement disponible avant de réinitialiser +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Le fournisseur continue de déclencher le disjoncteur +### Provider keeps tripping the circuit breaker -Si un fournisseur entre à plusieurs reprises dans l’état OPEN : +If a provider repeatedly enters OPEN state: -1. Vérifiez **Tableau de bord → Santé → Santé du fournisseur** pour connaître le modèle d'échec. -2. Accédez à **Paramètres → Résilience → Profils de fournisseur** et augmentez le seuil d'échec. -3. Vérifiez si le fournisseur a modifié les limites de l'API ou nécessite une ré-authentification -4. Examinez la télémétrie de latence : une latence élevée peut provoquer des échecs liés au délai d'attente. +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problèmes de transcription audio +## Audio Transcription Issues -### Erreur "Modèle non pris en charge" +### "Unsupported model" error -- Assurez-vous d'utiliser le préfixe correct : `deepgram/nova-3` ou `assemblyai/best` -- Vérifiez que le fournisseur est connecté dans **Tableau de bord → Fournisseurs** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### La transcription revient vide ou échoue +### Transcription returns empty or fails -- Vérifiez les formats audio pris en charge : `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Vérifiez que la taille du fichier est dans les limites du fournisseur (généralement < 25 Mo) -- Vérifier la validité de la clé API du fournisseur dans la carte du fournisseur +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Débogage du traducteur +## Translator Debugging -Utilisez **Tableau de bord → Traducteur** pour déboguer les problèmes de traduction de format : +Use **Dashboard → Translator** to debug format translation issues: -| Mode | Quand utiliser | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------- | -| **Aire de jeux** | Comparez les formats d'entrée/sortie côte à côte : collez une requête qui a échoué pour voir comment elle se traduit | -| **Testeur de chat** | Envoyez des messages en direct et inspectez la charge utile complète de la demande/réponse, y compris les en-têtes | -| **Banc d'essai** | Exécutez des tests par lots sur les combinaisons de formats pour identifier les traductions défectueuses | -| **Moniteur en direct** | Observez le flux de requêtes en temps réel pour détecter les problèmes de traduction intermittents | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Problèmes de format courants +### Common format issues -- **Les balises de réflexion n'apparaissent pas** — Vérifiez si le fournisseur cible prend en charge la réflexion et le paramètre de budget de réflexion -- **Abandon des appels d'outils** — Certaines traductions de format peuvent supprimer des champs non pris en charge ; vérifier en mode Playground -- **Invite système manquante** — Claude et Gemini gèrent les invites système différemment ; vérifier le résultat de la traduction -- **Le SDK renvoie une chaîne brute au lieu d'un objet** — Corrigé dans la version 1.1.0 : le désinfectant de réponse supprime désormais les champs non standard (`x_groq`, `usage_breakdown`, etc.) qui provoquent des échecs de validation OpenAI SDK Pydantic -- **GLM/ERNIE rejette le rôle `system`** — Corrigé dans la version 1.1.0 : le normalisateur de rôle fusionne automatiquement les messages système dans les messages utilisateur pour les modèles incompatibles -- **Rôle `developer` non reconnu** — Corrigé dans la v1.1.0 : automatiquement converti en `system` pour les fournisseurs non OpenAI -- **`json_schema` ne fonctionne pas avec Gemini** — Corrigé dans la version 1.1.0 : `response_format` est maintenant converti en `responseMimeType` + `responseSchema` de Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Paramètres de résilience +## Resilience Settings -### La limite de débit automatique ne se déclenche pas +### Auto rate-limit not triggering -- La limite de débit automatique s'applique uniquement aux fournisseurs de clés API (pas à OAuth/abonnement) -- Vérifiez que **Paramètres → Résilience → Profils de fournisseur** a activé la limite de débit automatique. -- Vérifiez si le fournisseur renvoie les codes d'état `429` ou les en-têtes `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Réglage de l'intervalle exponentiel +### Tuning exponential backoff -Les profils de fournisseur prennent en charge ces paramètres : +Provider profiles support these settings: -- **Délai de base** — Temps d'attente initial après le premier échec (par défaut : 1 s) -- **Délai maximum** — Limite maximale du temps d'attente (par défaut : 30 s) -- **Multiplicateur** — De combien augmenter le délai par échec consécutif (par défaut : 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Troupeau anti-tonnerre +### Anti-thundering herd -Lorsque de nombreuses requêtes simultanées atteignent un fournisseur à débit limité, OmniRoute utilise mutex + limitation de débit automatique pour sérialiser les requêtes et éviter les échecs en cascade. Ceci est automatique pour les fournisseurs de clés API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Toujours bloqué ? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Problèmes GitHub** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture** : voir [link](ARCHITECTURE.md) pour les détails internes -- **Référence API** : voir [link](API_REFERENCE.md) pour tous les points de terminaison -- **Tableau de bord de santé** : consultez **Tableau de bord → Santé** pour connaître l'état du système en temps réel -- **Traducteur** : utilisez **Tableau de bord → Traducteur** pour déboguer les problèmes de format +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/fr/USER_GUIDE.md b/docs/i18n/fr/USER_GUIDE.md index 6b395ee48b..5a043224df 100644 --- a/docs/i18n/fr/USER_GUIDE.md +++ b/docs/i18n/fr/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Guide de l'utilisateur +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Guide complet pour configurer les fournisseurs, créer des combos, intégrer des outils CLI et déployer OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Table des matières +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Guide complet pour configurer les fournisseurs, créer des combos, intégrer des --- -## 💰 Aperçu des prix +## 💰 Pricing at a Glance -| Niveau | Fournisseur | Coût | Réinitialisation des quotas | Idéal pour | -| ----------------- | --------------------- | ------------------------ | --------------------------- | --------------------------------- | -| **💳 ABONNEMENT** | Claude Code (Pro) | 20 $/mois | 5h + hebdomadaire | Déjà abonné | -| | Codex (Plus/Pro) | 20-200 $/mois | 5h + hebdomadaire | Utilisateurs d'OpenAI | -| | CLI Gémeaux | **GRATUIT** | 180K/mois + 1K/jour | Tout le monde! | -| | Copilote GitHub | 10-19 $/mois | Mensuel | Utilisateurs GitHub | -| **🔑 CLÉ API** | Recherche profonde | Paiement à l'utilisation | Aucun | Raisonnement bon marché | -| | Groq | Paiement à l'utilisation | Aucun | Inférence ultra-rapide | -| | xAI (Grok) | Paiement à l'utilisation | Aucun | Raisonnement Grok 4 | -| | Mistral | Paiement à l'utilisation | Aucun | Modèles hébergés dans l'UE | -| | Perplexité | Paiement à l'utilisation | Aucun | Recherche augmentée | -| | Ensemble IA | Paiement à l'utilisation | Aucun | Modèles open source | -| | IA de feux d'artifice | Paiement à l'utilisation | Aucun | Images FLUX rapides | -| | Cérébraux | Paiement à l'utilisation | Aucun | Vitesse à l'échelle d'une tranche | -| | Cohérer | Paiement à l'utilisation | Aucun | Commande R+ RAG | -| | NIM NVIDIA | Paiement à l'utilisation | Aucun | Modèles d'entreprise | -| **💰 BON MARCHÉ** | GLM-4.7 | 0,6 $/1 M | Tous les jours 10h | Sauvegarde budgétaire | -| | MiniMax M2.1 | 0,2 $/1 M | 5 heures roulantes | Option la moins chère | -| | Kimi K2 | 9 $/mois plat | 10 millions de jetons/mois | Coût prévisible | -| **🆓 GRATUIT** | iFlow | 0 $ | Illimité | 8 modèles gratuits | -| | Qwen | 0 $ | Illimité | 3 modèles gratuits | -| | Kiro | 0 $ | Illimité | Claude gratuit | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Conseil de pro :** Commencez avec Gemini CLI (180 000 gratuits/mois) + combo iFlow (gratuit et illimité) = 0 $ de coût ! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Cas d'utilisation +## 🎯 Use Cases -### Cas 1 : "J'ai un abonnement Claude Pro" +### Case 1: "I have Claude Pro subscription" -**Problème :** Le quota expire sans être utilisé, limites de débit lors d'un codage intensif +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Cas 2 : "Je veux un coût nul" +### Case 2: "I want zero cost" -**Problème :** Je ne peux pas payer les abonnements, j'ai besoin d'un codage IA fiable +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Cas 3 : "J'ai besoin de coder 24h/24 et 7j/7, sans interruption" +### Case 3: "I need 24/7 coding, no interruptions" -**Problème :** Délais, je ne peux pas me permettre de temps d'arrêt +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Cas 4 : "Je veux une IA GRATUITE dans OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Problème :** Besoin d'un assistant IA dans les applications de messagerie, entièrement gratuit +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Configuration du fournisseur +## 📖 Provider Setup -### 🔐 Fournisseurs d'abonnements +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Conseil de pro :** Utilisez Opus pour les tâches complexes, Sonnet pour la rapidité. OmniRoute suit le quota par modèle ! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### Codex OpenAI (Plus/Pro) +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (180 000 GRATUITS/mois !) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Meilleur rapport qualité-prix :** Énorme niveau gratuit ! Utilisez-le avant les niveaux payants. +**Best Value:** Huge free tier! Use this before paid tiers. -#### Copilote GitHub +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Fournisseurs bon marché +### 💰 Cheap Providers -#### GLM-4.7 (réinitialisation quotidienne, 0,6 $/1 million) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Inscrivez-vous : [Zhipu AI](https://open.bigmodel.cn/) -2. Obtenez la clé API du plan de codage -3. Tableau de bord → Ajouter une clé API : Fournisseur : `glm`, Clé API : `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Utilisez :** `glm/glm-4.7` — **Conseil de pro :** Le plan de codage offre un quota de 3 × à un coût de 1/7 ! Réinitialisation quotidienne à 10h00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (réinitialisation de 5 h, 0,20 $/1 M) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Inscrivez-vous : [MiniMax](https://www.minimax.io/) -2. Obtenir la clé API → Tableau de bord → Ajouter une clé API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Utilisez :** `minimax/MiniMax-M2.1` — **Conseil de pro :** Option la moins chère pour un contexte long (1 million de jetons) ! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (9$/mois fixe) +#### Kimi K2 ($9/month flat) -1. Abonnez-vous : [Moonshot AI](https://platform.moonshot.ai/) -2. Obtenir la clé API → Tableau de bord → Ajouter une clé API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Utilisez :** `kimi/kimi-latest` — **Conseil de pro :** Fixe 9 $/mois pour 10 millions de jetons = 0,90 $/1 million de coût effectif ! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 Fournisseurs GRATUITS +### 🆓 FREE Providers -#### iFlow (8 modèles GRATUITS) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 modèles GRATUITS) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRATUIT) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨Combinaisons +## 🎨 Combos -### Exemple 1 : Maximiser l'abonnement → Sauvegarde bon marché +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Exemple 2 : Gratuit uniquement (sans coût) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 Intégration CLI +## 🔧 CLI Integration -### IDE de curseur +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -###Claude Code +### Claude Code -Modifier `~/.claude/config.json` : +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Modifier `~/.claude/config.json` : } ``` -### CLI du Codex +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Modifier `~/.openclaw/openclaw.json` : +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Modifier `~/.openclaw/openclaw.json` : } ``` -**Ou utilisez le tableau de bord :** Outils CLI → OpenClaw → Configuration automatique +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Continuer / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Déploiement +## 🚀 Deployment -### Déploiement VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,81 +403,84 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Pour le mode intégré à l'hôte avec les binaires CLI, consultez la section Docker dans la documentation principale. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Variables d'environnement +### Environment Variables -| Variables | Par défaut | Descriptif | -| --------------------- | ------------------------------------ | ------------------------------------------------------------------------------ | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Secret de signature JWT (**changement de production**) | -| `INITIAL_PASSWORD` | `123456` | Mot de passe de première connexion | -| `DATA_DIR` | `~/.omniroute` | Répertoire de données (base de données, utilisation, journaux) | -| `PORT` | cadre par défaut | Port de service (`20128` dans les exemples) | -| `HOSTNAME` | cadre par défaut | Lier l'hôte (Docker par défaut est `0.0.0.0`) | -| `NODE_ENV` | valeur par défaut d'exécution | Définissez `production` pour le déploiement | -| `BASE_URL` | `http://localhost:20128` | URL de base interne côté serveur | -| `CLOUD_URL` | `https://omniroute.dev` | URL de base du point de terminaison de synchronisation cloud | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Secret HMAC pour les clés API générées | -| `REQUIRE_API_KEY` | `false` | Appliquer la clé API Bearer sur `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Active les journaux de requêtes/réponses | -| `AUTH_COOKIE_SECURE` | `false` | Forcer le cookie d'authentification `Secure` (derrière le proxy inverse HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Pour la référence complète des variables d'environnement, consultez le [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Modèles disponibles +## 📊 Available Models
-Voir tous les modèles disponibles +View all available models -**Code Claude (`cc/`)** — Pro/Max : `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Codex (`cx/`)** — Plus/Pro : `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATUIT : `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Copilote GitHub (`gh/`)** : `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — 0,6 $/1 million : `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — 0,2 $/1 million : `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATUIT : `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATUIT : `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATUIT : `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` -**Recherche profonde (`ds/`)** : `ds/deepseek-chat`, `ds/deepseek-reasoner` +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` -**Groq (`groq/`)** : `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` -**xAI (`xai/`)** : `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` +**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**Mistral (`mistral/`)** : `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Perplexité (`pplx/`)** : `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Ensemble IA (`together/`)** : `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**IA de feux d'artifice (`fireworks/`)** : `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Cérébras (`cerebras/`)** : `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Cohérer (`cohere/`)** : `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` -**NIM NVIDIA (`nvidia/`)** : `nvidia/nvidia/llama-3.3-70b-instruct` +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
--- -## 🧩 Fonctionnalités avancées +## 🧩 Advanced Features -### Modèles personnalisés +### Custom Models -Ajoutez n'importe quel ID de modèle à n'importe quel fournisseur sans attendre une mise à jour de l'application : +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Ou utilisez le tableau de bord : **Fournisseurs → [Fournisseur] → Modèles personnalisés**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Itinéraires de fournisseurs dédiés +### Dedicated Provider Routes -Acheminez les demandes directement vers un fournisseur spécifique avec validation du modèle : +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Le préfixe du fournisseur est ajouté automatiquement s'il est manquant. Les modèles incompatibles renvoient `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Configuration du proxy réseau +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Précédence :** Spécifique à la clé → Spécifique au combo → Spécifique au fournisseur → Global → Environnement. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API du catalogue de modèles +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Renvoie les modèles regroupés par fournisseur avec des types (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Synchronisation avec le cloud +### Cloud Sync -- Synchronisez les fournisseurs, les combos et les paramètres sur tous les appareils -- Synchronisation automatique en arrière-plan avec délai d'attente + échec rapide -- Préférer le côté serveur `BASE_URL`/`CLOUD_URL` en production +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production ### LLM Gateway Intelligence (Phase 9) -- **Cache sémantique** — Met en cache automatiquement les réponses hors streaming, température = 0 (contourner avec `X-OmniRoute-No-Cache: true`) -- **Demande d'idempotence** — Déduplique les requêtes dans les 5 secondes via l'en-tête `Idempotency-Key` ou `X-Request-Id` -- **Suivi des progrès** – Événements SSE `event: progress` opt-in via l'en-tête `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Aire de jeux des traducteurs +### Translator Playground -Accès via **Tableau de bord → Traducteur**. Déboguez et visualisez comment OmniRoute traduit les requêtes API entre les fournisseurs. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Mode | Objectif | -| ---------------------- | ------------------------------------------------------------------------------------------------------------- | -| **Aire de jeux** | Sélectionnez les formats source/cible, collez une requête et voyez instantanément le résultat traduit | -| **Testeur de chat** | Envoyez des messages de chat en direct via le proxy et inspectez le cycle complet de demande/réponse | -| **Banc d'essai** | Exécutez des tests par lots sur plusieurs combinaisons de formats pour vérifier l'exactitude de la traduction | -| **Moniteur en direct** | Regardez les traductions en temps réel à mesure que les demandes transitent par le proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Cas d'utilisation :** +**Use cases:** -- Déboguer pourquoi une combinaison client/fournisseur spécifique échoue -- Vérifiez que les balises de réflexion, les appels d'outils et les invites système se traduisent correctement -- Comparez les différences de format entre les formats API OpenAI, Claude, Gemini et Responses +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Stratégies de routage +### Routing Strategies -Configurez via **Tableau de bord → Paramètres → Routage**. +Configure via **Dashboard → Settings → Routing**. -| Stratégie | Descriptif | -| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| **Remplir en premier** | Utilise les comptes par ordre de priorité : le compte principal gère toutes les demandes jusqu'à ce qu'il soit indisponible | -| **Tournoi à la ronde** | Parcourt tous les comptes avec une limite persistante configurable (par défaut : 3 appels par compte) | -| **P2C (Puissance de deux choix)** | Sélectionne 2 comptes aléatoires et oriente vers le compte le plus sain – équilibre la charge avec la conscience de la santé | -| **Aléatoire** | Sélectionne au hasard un compte pour chaque demande à l'aide de Fisher-Yates shuffle | -| **Le moins utilisé** | Routes vers le compte avec l'horodatage `lastUsedAt` le plus ancien, répartissant le trafic de manière uniforme | -| **Coût optimisé** | Itinéraires vers le compte avec la valeur de priorité la plus faible, optimisation pour les fournisseurs les moins chers | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Alias de modèles génériques +#### Wildcard Model Aliases -Créez des modèles génériques pour remapper les noms de modèles : +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Les caractères génériques prennent en charge `*` (n'importe quel caractère) et `?` (un seul caractère). +Wildcards support `*` (any characters) and `?` (single character). -#### Chaînes de secours +#### Fallback Chains -Définissez des chaînes de secours globales qui s'appliquent à toutes les requêtes : +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Résilience et disjoncteurs +### Resilience & Circuit Breakers -Configurez via **Tableau de bord → Paramètres → Résilience**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute met en œuvre la résilience au niveau du fournisseur avec quatre composants : +OmniRoute implements provider-level resilience with four components: -1. **Profils de fournisseur** — Configuration par fournisseur pour : - - Seuil de défaillance (combien de défaillances avant ouverture) - - Durée du temps de recharge - - Sensibilité de détection de limite de débit - - Paramètres d'intervalle exponentiel +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Limites de débit modifiables** — Paramètres par défaut au niveau du système configurables dans le tableau de bord : - - **Requêtes par minute (RPM)** — Nombre maximal de requêtes par minute et par compte - - **Min Time Between Requests** — Écart minimum en millisecondes entre les requêtes - - **Max Concurrent Requests** — Nombre maximal de requêtes simultanées par compte - - Cliquez sur **Modifier** pour modifier, puis sur **Enregistrer** ou **Annuler**. Les valeurs persistent via l'API de résilience. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Disjoncteur** — Suit les pannes par fournisseur et ouvre automatiquement le circuit lorsqu'un seuil est atteint : - - **FERMÉ** (sain) — Les demandes circulent normalement - - **OPEN** — Le fournisseur est temporairement bloqué après des échecs répétés - - **HALF_OPEN** — Test si le fournisseur a récupéré +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Politiques et identifiants verrouillés** — Affiche l'état du disjoncteur et les identifiants verrouillés avec capacité de déverrouillage forcé. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Détection automatique des limites de débit** — Surveille les en-têtes `429` et `Retry-After` pour éviter de manière proactive d'atteindre les limites de débit du fournisseur. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Conseil de pro :** Utilisez le bouton **Réinitialiser tout** pour effacer tous les disjoncteurs et les temps de recharge lorsqu'un fournisseur se remet d'une panne. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Exportation/Importation de base de données +### Database Export / Import -Gérez les sauvegardes de base de données dans **Tableau de bord → Paramètres → Système et stockage**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Actions | Descriptif | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Exporter la base de données** | Télécharge la base de données SQLite actuelle sous forme de fichier `.sqlite` | -| **Exporter tout (.tar.gz)** | Télécharge une archive de sauvegarde complète comprenant : base de données, paramètres, combos, connexions du fournisseur (pas d'informations d'identification), métadonnées de la clé API | -| **Importer la base de données** | Téléchargez un fichier `.sqlite` pour remplacer la base de données actuelle. Une sauvegarde de pré-importation est automatiquement créée | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Validation de l'importation :** Le fichier importé est validé pour son intégrité (vérification pragma SQLite), les tables requises (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) et sa taille (max 100 Mo). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Cas d'utilisation :** +**Use Cases:** -- Migrer OmniRoute entre machines -- Créer des sauvegardes externes pour la reprise après sinistre -- Partager les configurations entre les membres de l'équipe (exporter tout → partager l'archive) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Tableau de bord des paramètres +### Settings Dashboard -La page des paramètres est organisée en 5 onglets pour une navigation facile : +The settings page is organized into 5 tabs for easy navigation: -| Onglet | Contenu | -| -------------- | ------------------------------------------------------------------------------------------------------------------------ | -| **Sécurité** | Paramètres de connexion/mot de passe, contrôle d'accès IP, authentification API pour `/models` et blocage du fournisseur | -| **Routage** | Stratégie de routage globale (6 options), alias de modèle générique, chaînes de secours, valeurs par défaut combinées | -| **Résilience** | Profils de fournisseurs, limites de débit modifiables, état du disjoncteur, politiques et identifiants verrouillés | -| **IA** | Configuration du budget de réflexion, injection d'invite du système global, statistiques de cache d'invite | -| **Avancé** | Configuration globale du proxy (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Gestion des coûts et du budget +### Costs & Budget Management -Accès via **Tableau de bord → Coûts**. +Access via **Dashboard → Costs**. -| Onglet | Objectif | -| ---------- | ---------------------------------------------------------------------------------------------------------------------- | -| **Budget** | Fixez des limites de dépenses par clé API avec des budgets quotidiens/hebdomadaires/mensuels et un suivi en temps réel | -| **Tarif** | Afficher et modifier les entrées de tarification du modèle — coût par 1 000 jetons d'entrée/sortie par fournisseur | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Suivi des coûts :** Chaque demande enregistre l'utilisation du jeton et calcule le coût à l'aide du tableau de tarification. Affichez les répartitions dans **Tableau de bord → Utilisation** par fournisseur, modèle et clé API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Transcription audio +### Audio Transcription -OmniRoute prend en charge la transcription audio via le point de terminaison compatible OpenAI : +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Fournisseurs disponibles : **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Formats audio pris en charge : `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Stratégies d'équilibrage des combos +### Combo Balancing Strategies -Configurez l'équilibrage par combo dans **Tableau de bord → Combos → Créer/Modifier → Stratégie**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Stratégie | Descriptif | -| ---------------------- | ----------------------------------------------------------------------------------------------- | -| **Robin à la ronde** | Tourne à travers les modèles de manière séquentielle | -| **Priorité** | Essaie toujours le premier modèle ; se rabat uniquement sur l'erreur | -| **Aléatoire** | Sélectionne un modèle aléatoire dans le combo pour chaque demande | -| **Pondéré** | Itinéraires proportionnellement basés sur les poids attribués par modèle | -| **Les moins utilisés** | Itinéraires vers le modèle avec le moins de requêtes récentes (utilise des métriques combinées) | -| **Coût optimisé** | Itinéraires vers le modèle disponible le moins cher (utilise le tableau de prix) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Les valeurs par défaut des combos globaux peuvent être définies dans **Tableau de bord → Paramètres → Routage → Paramètres par défaut des combos**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Tableau de bord de santé +### Health Dashboard -Accès via **Tableau de bord → Santé**. Aperçu de l'état du système en temps réel avec 6 cartes : +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Carte | Ce que cela montre | -| ------------------------- | --------------------------------------------------------------------------- | -| **État du système** | Disponibilité, version, utilisation de la mémoire, répertoire de données | -| **Santé du fournisseur** | État du disjoncteur par fournisseur (Fermé/Ouvert/Semi-ouvert) | -| **Limites de taux** | Temps de recharge de la limite de débit actif par compte avec temps restant | -| **Verrouillages actifs** | Fournisseurs temporairement bloqués par la politique de verrouillage | -| **Cache de signatures** | Statistiques du cache de déduplication (clés actives, taux de réussite) | -| **Télémétrie de latence** | Agrégation de latence p50/p95/p99 par fournisseur | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Conseil de pro :** La page Santé s'actualise automatiquement toutes les 10 secondes. Utilisez la carte disjoncteur pour identifier les fournisseurs qui rencontrent des problèmes. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/he/API_REFERENCE.md b/docs/i18n/he/API_REFERENCE.md index f96c9af470..b795722c11 100644 --- a/docs/i18n/he/API_REFERENCE.md +++ b/docs/i18n/he/API_REFERENCE.md @@ -1,12 +1,12 @@ -# הפניה ל-API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -הפניה מלאה עבור כל נקודות הקצה של OmniRoute API. +Complete reference for all OmniRoute API endpoints. --- -## תוכן העניינים +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## השלמות של צ'אט +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### כותרות מותאמות אישית +### Custom Headers -| כותרת | כיוון | תיאור | -| ------------------------ | ----- | --------------------------------- | -| `X-OmniRoute-No-Cache` | בקשה | הגדר ל-`true` כדי לעקוף את המטמון | -| `X-OmniRoute-Progress` | בקשה | הגדר ל-`true` עבור אירועי התקדמות | -| `Idempotency-Key` | בקשה | מפתח Dedup (חלון 5 שניות) | -| `X-Request-Id` | בקשה | מפתח ניקוי חלופי | -| `X-OmniRoute-Cache` | תגובה | `HIT` או `MISS` (לא סטרימינג) | -| `X-OmniRoute-Idempotent` | תגובה | `true` אם ביטול כפילות | -| `X-OmniRoute-Progress` | תגובה | `enabled` אם מעקב ההתקדמות ב- | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## הטבעות +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -ספקים זמינים: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## יצירת תמונה +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -ספקים זמינים: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## רשימת דגמים +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## נקודות קצה של תאימות +## Compatibility Endpoints -| שיטה | נתיב | פורמט | -| ---- | --------------------------- | ----------------- | -| פוסט | `/v1/chat/completions` | OpenAI | -| פוסט | `/v1/messages` | אנתרופית | -| פוסט | `/v1/responses` | OpenAI תגובות | -| פוסט | `/v1/embeddings` | OpenAI | -| פוסט | `/v1/images/generations` | OpenAI | -| קבל | `/v1/models` | OpenAI | -| פוסט | `/v1/messages/count_tokens` | אנתרופית | -| קבל | `/v1beta/models` | מזל תאומים | -| פוסט | `/v1beta/models/{...path}` | תאומים ליצור תוכן | -| פוסט | `/v1/api/chat` | אולמה | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### מסלולי ספקים ייעודיים +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -קידומת הספק מתווספת אוטומטית אם חסרה. דגמים לא תואמים מחזירים `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## מטמון סמנטי +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -דוגמה לתגובה: +Response example: ```json { @@ -162,154 +162,164 @@ DELETE /api/cache --- -## לוח מחוונים וניהול +## Dashboard & Management -### אימות +### Authentication -| נקודת קצה | שיטה | תיאור | -| ----------------------------- | ------- | ----------------- | -| `/api/auth/login` | פוסט | כניסה | -| `/api/auth/logout` | פוסט | התנתק | -| `/api/settings/require-login` | GET/PUT | החלפת כניסה נדרשת | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### ניהול ספקים +### Provider Management -| נקודת קצה | שיטה | תיאור | -| ---------------------------- | -------------- | ------------------- | -| `/api/providers` | קבל/פוסט | רשימת / צור ספקים | -| `/api/providers/[id]` | GET/PUT/DELETE | ניהול ספק | -| `/api/providers/[id]/test` | פוסט | בדיקת חיבור ספק | -| `/api/providers/[id]/models` | קבל | רשימת דגמי ספקים | -| `/api/providers/validate` | פוסט | אימות תצורת ספק | -| `/api/provider-nodes*` | שונים | ניהול צומת ספק | -| `/api/provider-models` | קבל/פרסם/מחק | דגמים מותאמים אישית | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | ### OAuth Flows -| נקודת קצה | שיטה | תיאור | -| -------------------------------- | ----- | ----------------- | -| `/api/oauth/[provider]/[action]` | שונים | OAuth ספציפי לספק | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### ניתוב ותצורה +### Routing & Config -| נקודת קצה | שיטה | תיאור | -| --------------------- | -------- | ----------------------- | -| `/api/models/alias` | קבל/פוסט | כינויי מודל | -| `/api/models/catalog` | קבל | כל הדגמים לפי ספק + סוג | -| `/api/combos*` | שונים | ניהול קומבו | -| `/api/keys*` | שונים | ניהול מפתחות API | -| `/api/pricing` | קבל | תמחור דגם | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### שימוש וניתוח +### Usage & Analytics -| נקודת קצה | שיטה | תיאור | -| --------------------------- | ---- | ----------------- | -| `/api/usage/history` | קבל | היסטוריית שימוש | -| `/api/usage/logs` | קבל | יומני שימוש | -| `/api/usage/request-logs` | קבל | יומנים ברמת הבקשה | -| `/api/usage/[connectionId]` | קבל | שימוש לכל חיבור | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### הגדרות +### Settings -| נקודת קצה | שיטה | תיאור | -| ------------------------------- | ------- | --------------------------- | -| `/api/settings` | GET/PUT | הגדרות כלליות | -| `/api/settings/proxy` | GET/PUT | תצורת proxy של רשת | -| `/api/settings/proxy/test` | פוסט | בדיקת חיבור פרוקסי | -| `/api/settings/ip-filter` | GET/PUT | רשימת הרשאות IP/רשימת חסימה | -| `/api/settings/thinking-budget` | GET/PUT | תקציב סמלי מנמק | -| `/api/settings/system-prompt` | GET/PUT | הודעת מערכת גלובלית | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### ניטור +### Monitoring -| נקודת קצה | שיטה | תיאור | -| ------------------------ | ------- | ---------------------- | -| `/api/sessions` | קבל | מעקב הפעלה פעיל | -| `/api/rate-limits` | קבל | מגבלות תעריף לחשבון | -| `/api/monitoring/health` | קבל | בדיקת בריאות | -| `/api/cache` | קבל/מחק | סטטיסטיקות מטמון / נקה | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### גיבוי וייצוא/ייבוא +### Backup & Export/Import -| נקודת קצה | שיטה | תיאור | -| --------------------------- | ---- | -------------------------------------- | -| `/api/db-backups` | קבל | רשימת גיבויים זמינים | -| `/api/db-backups` | PUT | צור גיבוי ידני | -| `/api/db-backups` | פוסט | שחזור מגיבוי ספציפי | -| `/api/db-backups/export` | קבל | הורד את מסד הנתונים כקובץ sqlite | -| `/api/db-backups/import` | פוסט | העלה קובץ sqlite כדי להחליף מסד נתונים | -| `/api/db-backups/exportAll` | קבל | הורד גיבוי מלא כארכיון .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### סנכרון ענן +### Cloud Sync -| נקודת קצה | שיטה | תיאור | -| ---------------------- | ----- | ------------------ | -| `/api/sync/cloud` | שונים | פעולות סנכרון בענן | -| `/api/sync/initialize` | פוסט | אתחול סנכרון | -| `/api/cloud/*` | שונים | ניהול ענן | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### כלי CLI +### CLI Tools -| נקודת קצה | שיטה | תיאור | -| ---------------------------------- | ---- | -------------------- | -| `/api/cli-tools/claude-settings` | קבל | סטטוס קלוד CLI | -| `/api/cli-tools/codex-settings` | קבל | מצב Codex CLI | -| `/api/cli-tools/droid-settings` | קבל | סטטוס CLI של Droid | -| `/api/cli-tools/openclaw-settings` | קבל | מצב CLI של OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | קבל | זמן ריצה כללי של CLI | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -תגובות CLI כוללות: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### מגבלות חוסן וקצב +### ACP Agents -| נקודת קצה | שיטה | תיאור | -| ----------------------- | ------- | --------------------------- | -| `/api/resilience` | GET/PUT | קבל/עדכן פרופילי חוסן | -| `/api/resilience/reset` | פוסט | איפוס מפסקים | -| `/api/rate-limits` | קבל | סטטוס מגבלת תעריף לכל חשבון | -| `/api/rate-limit` | קבל | תצורת מגבלת תעריף גלובלית | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### איוואלים +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| נקודת קצה | שיטה | תיאור | -| ------------ | -------- | ------------------------------ | -| `/api/evals` | קבל/פוסט | רשימת חבילות eval / הפעל הערכה | +### Resilience & Rate Limits -### מדיניות +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| נקודת קצה | שיטה | תיאור | -| --------------- | ------------ | ----------------- | -| `/api/policies` | קבל/פרסם/מחק | נהל מדיניות ניתוב | +### Evals -### תאימות +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| נקודת קצה | שיטה | תיאור | -| --------------------------- | ---- | -------------------------- | -| `/api/compliance/audit-log` | קבל | יומן ביקורת ציות (N אחרון) | +### Policies -### v1beta (תואם לתאומים) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| נקודת קצה | שיטה | תיאור | -| -------------------------- | ---- | ---------------------------------- | -| `/v1beta/models` | קבל | רשימת דגמים בפורמט תאומים | -| `/v1beta/models/{...path}` | פוסט | תאומים `generateContent` נקודת קצה | +### Compliance -נקודות קצה אלו משקפות את פורמט ה-API של Gemini עבור לקוחות המצפים לתאימות מקורית של Gemini SDK. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### ממשקי API פנימיים/מערכתיים +### v1beta (Gemini-Compatible) -| נקודת קצה | שיטה | תיאור | -| --------------- | ---- | --------------------------------------------- | -| `/api/init` | קבל | בדיקת אתחול האפליקציה (בשימוש בהפעלה הראשונה) | -| `/api/tags` | קבל | תגיות מודל תואמות אולמה (ללקוחות אולמה) | -| `/api/restart` | פוסט | הפעל מחדש את השרת החינני | -| `/api/shutdown` | פוסט | הפעל כיבוי שרת חינני | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **הערה:** נקודות קצה אלו משמשות באופן פנימי על ידי המערכת או עבור תאימות לקוח Ollama. הם לא נקראים בדרך כלל על ידי משתמשי קצה. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## תמלול אודיו +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -תמלול קבצי אודיו באמצעות Deepgram או AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**בקשה:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**תגובה:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**ספקים נתמכים:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**פורמטים נתמכים:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## תאימות אולמה +## Ollama Compatibility -עבור לקוחות המשתמשים בפורמט ה-API של Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -בקשות מתורגמות אוטומטית בין אולמה לפורמטים פנימיים. +Requests are automatically translated between Ollama and internal formats. --- -## טלמטריה +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**תגובה:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## תקציב +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## זמינות דגם +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## עיבוד הבקשה +## Request Processing -1. הלקוח שולח בקשה אל `/v1/*` -2. מטפל במסלול קורא `handleChat`, `handleEmbedding`, `handleAudioTranscription`, או `handleImageGeneration` -3. המודל נפתר (ספק ישיר/דגם או כינוי/שילוב) -4. אישורים נבחרים מ-DB מקומי עם סינון זמינות חשבון -5. לצ'אט: `handleChatCore` — זיהוי פורמט, תרגום, בדיקת מטמון, בדיקת אימפוטנציה -6. מנהל הספק שולח בקשה במעלה הזרם -7. תגובה מתורגמת חזרה לפורמט הלקוח (צ'אט) או הוחזרה כפי שהיא (הטמעות/תמונות/שמע) -8. שימוש/רישום נרשם -9. Fallback חל על שגיאות בהתאם לכללי המשולבים +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -הפניה מלאה לארכיטקטורה: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## אימות +## Authentication -- מסלולי לוח המחוונים (`/dashboard/*`) משתמשים בקובץ cookie `auth_token` -- הכניסה משתמשת ב-hash סיסמה שמורה; חזרה ל-`INITIAL_PASSWORD` -- `requireLogin` ניתן להחלפה באמצעות `/api/settings/require-login` -- מסלולי `/v1/*` דורשים אופציונלי מפתח API של Bearer כאשר `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/he/ARCHITECTURE.md b/docs/i18n/he/ARCHITECTURE.md index 5f92f8976c..258d62df53 100644 --- a/docs/i18n/he/ARCHITECTURE.md +++ b/docs/i18n/he/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# ארכיטקטורת OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_עדכון אחרון: 2026-02-18_ +_Last updated: 2026-03-04_ -## תקציר מנהלים +## Executive Summary -OmniRoute הוא שער ולוח מחוונים מקומיים לניתוב בינה מלאכותית הבנויים על Next.js. -הוא מספק נקודת קצה אחת תואמת OpenAI (`/v1/*`) ומנתב תעבורה על פני מספר ספקים במעלה הזרם עם תרגום, חזרה, רענון אסימון ומעקב אחר שימוש. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -יכולות ליבה: +Core capabilities: -- משטח API תואם OpenAI עבור CLI/כלים (28 ספקים) -- תרגום בקשה/תשובה בין פורמטים של ספקים -- נפילה משולבת דגם (רצף מרובה דגמים) -- חזרה ברמת החשבון (ריבוי חשבון לכל ספק) -- ניהול חיבורי ספק מפתח OAuth + API -- יצירת הטמעה באמצעות `/v1/embeddings` (6 ספקים, 9 דגמים) -- יצירת תמונות באמצעות `/v1/images/generations` (4 ספקים, 9 דגמים) -- חשבו על ניתוח תגים (`...`) עבור מודלים של חשיבה -- חיטוי תגובה עבור תאימות קפדנית של OpenAI SDK -- נורמליזציה של תפקידים (מפתח → מערכת, מערכת → משתמש) עבור תאימות בין ספקים -- המרת פלט מובנית (json_schema → Gemini responseSchema) -- התמדה מקומית לספקים, מפתחות, כינויים, שילובים, הגדרות, תמחור -- מעקב אחר שימוש/עלויות ורישום בקשות -- סנכרון ענן אופציונלי לסנכרון ריבוי מכשירים/מצבים -- רשימת היתרים/רשימת חסימה של IP עבור בקרת גישה ל-API -- חשיבה לניהול תקציב (מעבר/אוטומטי/מותאם אישית/מותאם) -- הזרקה מהירה של מערכת גלובלית -- מעקב אחר מפגשים וטביעות אצבע -- הגבלת תעריפים משופרת לכל חשבון עם פרופילים ספציפיים לספק -- דפוס מפסק עבור חוסן הספק -- הגנת עדר נגד רעמים עם נעילת mutex -- מטמון ביטול כפילויות של בקשה מבוסס חתימה -- שכבת דומיין: זמינות מודל, כללי עלות, מדיניות נפילה, מדיניות נעילה -- התמדה של מצב דומיין (מטמון כתיבה של SQLite עבור תקלות, תקציבים, נעילה, מפסקים) -- מנוע מדיניות להערכת בקשות מרוכזת (נעילה → תקציב → חזרה) -- בקש טלמטריה עם צבירה של חביון p50/p95/p99 -- מזהה מתאם (X-Request-Id) למעקב מקצה לקצה -- רישום ביקורת תאימות עם ביטול הסכמה לכל מפתח API -- מסגרת Eval לאבטחת איכות LLM -- לוח מחוונים של ממשק משתמש חוסן עם מצב מפסק בזמן אמת -- ספקי OAuth מודולריים (12 מודולים בודדים תחת `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -דגם זמן ריצה ראשי: +Primary runtime model: -- מסלולי אפליקציית Next.js תחת `src/app/api/*` מיישמים גם ממשקי API של לוח המחוונים וגם ממשקי API של תאימות -- ליבת SSE/ניתוב משותפת ב-`src/sse/*` + `open-sse/*` מטפלת בביצוע ספק, בתרגום, בסטרימינג, ב-fallback ושימוש +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## היקף וגבולות +## Scope and Boundaries -### בהיקף +### In Scope -- זמן ריצה של שער מקומי -- ממשקי API לניהול לוח מחוונים -- אימות ספק ורענון אסימון -- בקש תרגום והזרמת SSE -- מדינה מקומית + התמדה בשימוש -- תזמור סנכרון ענן אופציונלי +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### מחוץ לתחום +### Out of Scope -- הטמעת שירות ענן מאחורי `NEXT_PUBLIC_CLOUD_URL` -- ספק SLA/מטוס בקרה מחוץ לתהליך המקומי -- קבצי CLI חיצוניים עצמם (קלוד CLI, Codex CLI וכו') +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## הקשר מערכת ברמה גבוהה +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## רכיבי זמן ריצה ליבה +## Core Runtime Components -## 1) API ושכבת ניתוב (Next.js App Routes) +## 1) API and Routing Layer (Next.js App Routes) -ספריות עיקריות: +Main directories: -- `src/app/api/v1/*` ו`src/app/api/v1beta/*` עבור ממשקי API של תאימות -- `src/app/api/*` עבור ממשקי API לניהול/תצורה -- השכתוב הבא במפת `next.config.mjs` מפה `/v1/*` ל`/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -מסלולי תאימות חשובים: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` - כולל דגמים מותאמים אישית עם `custom: true` -- `src/app/api/v1/embeddings/route.ts` - יצירת הטמעה (6 ספקים) -- `src/app/api/v1/images/generations/route.ts` — יצירת תמונות (4+ ספקים כולל אנטי-כבידה/נביוס) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` - צ'אט ייעודי לכל ספק -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` - הטמעות ייעודיות לכל ספק -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` - תמונות ייעודיות לכל ספק +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -תחומי ניהול: +Management domains: -- אישור/הגדרות: `src/app/api/auth/*`, `src/app/api/settings/*` -- ספקים/חיבורים: `src/app/api/providers*` -- צמתי ספק: `src/app/api/provider-nodes*` -- דגמים מותאמים אישית: `src/app/api/provider-models` (GET/POST/DELETE) -- קטלוג דגמים: `src/app/api/models/catalog` (GET) -- תצורת פרוקסי: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- מפתחות/כינויים/שילובים/תמחור: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- שימוש: `src/app/api/usage/*` -- סנכרון/ענן: `src/app/api/sync/*`, `src/app/api/cloud/*` -- עוזרי כלי עבודה של CLI: `src/app/api/cli-tools/*` -- מסנן IP: `src/app/api/settings/ip-filter` (GET/PUT) -- תקציב חשיבה: `src/app/api/settings/thinking-budget` (GET/PUT) -- הודעת מערכת: `src/app/api/settings/system-prompt` (GET/PUT) -- הפעלות: `src/app/api/sessions` (GET) -- מגבלות תעריפים: `src/app/api/rate-limits` (GET) -- חוסן: `src/app/api/resilience` (GET/PATCH) - פרופילי ספקים, מפסק זרם, מצב מגבלת קצב -- איפוס חוסן: `src/app/api/resilience/reset` (POST) - מפסקי איפוס + התקררות -- סטטיסטיקות מטמון: `src/app/api/cache/stats` (GET/DELETE) -- זמינות דגם: `src/app/api/models/availability` (GET/POST) -- טלמטריה: `src/app/api/telemetry/summary` (GET) -- תקציב: `src/app/api/usage/budget` (GET/POST) -- שרשראות חוזרות: `src/app/api/fallback/chains` (GET/POST/DELETE) -- ביקורת ציות: `src/app/api/compliance/audit-log` (GET) -- ערכים: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- מדיניות: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + ליבת תרגום +## 2) SSE + Translation Core -מודולי זרימה עיקריים: +Main flow modules: -- כניסה: `src/sse/handlers/chat.ts` -- תזמור ליבה: `open-sse/handlers/chatCore.ts` -- מתאמי ביצוע של ספק: `open-sse/executors/*` -- זיהוי פורמט/תצורת ספק: `open-sse/services/provider.ts` -- ניתוח/פתרון מודל: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- לוגיקה חזרה לחשבון: `open-sse/services/accountFallback.ts` -- רישום תרגום: `open-sse/translator/index.ts` -- טרנספורמציות זרם: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- מיצוי/נורמליזציה של שימוש: `open-sse/utils/usageTracking.ts` -- מנתח תגיות חושב: `open-sse/utils/thinkTagParser.ts` -- מטפל בהטמעה: `open-sse/handlers/embeddings.ts` -- רישום ספקי הטבעה: `open-sse/config/embeddingRegistry.ts` -- מטפל ביצירת תמונות: `open-sse/handlers/imageGeneration.ts` -- רישום ספקי תמונות: `open-sse/config/imageRegistry.ts` -- חיטוי תגובה: `open-sse/handlers/responseSanitizer.ts` -- נורמליזציה של תפקידים: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -שירותים (היגיון עסקי): +Services (business logic): -- בחירת חשבון/ניקוד: `open-sse/services/accountSelector.ts` -- ניהול מחזור חיים בהקשר: `open-sse/services/contextManager.ts` -- אכיפת מסנן IP: `open-sse/services/ipFilter.ts` -- מעקב אחר פעילויות: `open-sse/services/sessionManager.ts` -- בקש ביטול כפילות: `open-sse/services/signatureCache.ts` -- הזרקת הודעה למערכת: `open-sse/services/systemPrompt.ts` -- ניהול תקציב חשיבה: `open-sse/services/thinkingBudget.ts` -- ניתוב דגם תווים כלליים: `open-sse/services/wildcardRouter.ts` -- ניהול מגבלת תעריפים: `open-sse/services/rateLimitManager.ts` -- מפסק חשמל: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -מודולי שכבת דומיין: +Domain layer modules: -- זמינות דגם: `src/lib/domain/modelAvailability.ts` -- כללי עלות/תקציבים: `src/lib/domain/costRules.ts` -- מדיניות סתירה: `src/lib/domain/fallbackPolicy.ts` -- פותר משולב: `src/lib/domain/comboResolver.ts` -- מדיניות נעילה: `src/lib/domain/lockoutPolicy.ts` -- מנוע מדיניות: `src/domain/policyEngine.ts` — נעילה מרכזית ← תקציב ← הערכה חוזרת -- קטלוג קודי שגיאה: `src/lib/domain/errorCodes.ts` -- מזהה בקשה: `src/lib/domain/requestId.ts` -- פסק זמן לאחזור: `src/lib/domain/fetchTimeout.ts` -- בקש טלמטריה: `src/lib/domain/requestTelemetry.ts` -- ציות/ביקורת: `src/lib/domain/compliance/index.ts` -- רץ Eval: `src/lib/domain/evalRunner.ts` -- התמדה של מצב דומיין: `src/lib/db/domainState.ts` — SQLite CRUD עבור רשתות חלופיות, תקציבים, היסטוריית עלויות, מצב נעילה, מפסקי חשמל +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -מודולי ספק OAuth (12 קבצים בודדים תחת `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- אינדקס הרישום: `src/lib/oauth/providers/index.ts` -- ספקים בודדים: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, , **\_119**, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- עטיפה דקה: `src/lib/oauth/providers.ts` - ייצוא מחדש ממודולים בודדים +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) שכבת התמדה +## 3) Persistence Layer -DB מצב ראשי: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- קובץ: `${DATA_DIR}/db.json` (או `$XDG_CONFIG_HOME/omniroute/db.json` כאשר מוגדר, אחרת `~/.omniroute/db.json`) -- ישויות: providerConnections, providerNodes, modelAliases, combos, apiKeys, הגדרות, תמחור, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **SystemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -DB שימוש: +Usage persistence: -- `src/lib/usageDb.ts` -- קבצים: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- פועל לפי אותה מדיניות ספריית בסיס כמו `localDb` (`DATA_DIR`, ולאחר מכן `XDG_CONFIG_HOME/omniroute` כאשר מוגדר) -- מפורקים לתת-מודולים ממוקדים: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present Domain State DB (SQLite): -- `src/lib/db/domainState.ts` - פעולות CRUD עבור מצב תחום -- טבלאות (נוצרו ב-`src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- דפוס כתיבה דרך מטמון: מפות בזיכרון הן סמכותיות בזמן ריצה; מוטציות נכתבות באופן סינכרוני ל-SQLite; המצב משוחזר מ-DB בהתחלה קרה +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) משטחי אימות + אבטחה +## 4) Auth + Security Surfaces -- אישור קובצי Cookie של לוח המחוונים: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- יצירת מפתח API/אימות: `src/shared/utils/apiKey.ts` -- סודות הספק נשארו בערכים `providerConnections` -- תמיכה ב-proxy יוצא דרך `open-sse/utils/proxyFetch.ts` (env vars) ו-`open-sse/utils/networkProxy.ts` (ניתן להגדרה לפי ספק או גלובלי) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) סנכרון ענן +## 5) Cloud Sync -- כניסת מתזמן: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- משימה תקופתית: `src/shared/services/cloudSyncScheduler.ts` -- מסלול שליטה: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## מחזור חיים של בקשה (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## תזרים משולב + חשבון נפילה +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -החלטות חילופין מונעות על ידי `open-sse/services/accountFallback.ts` באמצעות קודי מצב והיוריסטיקה של הודעת שגיאה. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## מחזור חיים של OAuth Onboarding ו-Token Refresh +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -רענון במהלך תעבורה חיה מתבצע בתוך `open-sse/handlers/chatCore.ts` באמצעות המבצע `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## מחזור חיים של סנכרון ענן (אפשר / סנכרון / השבת) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -סנכרון תקופתי מופעל על ידי `CloudSyncScheduler` כאשר ענן מופעל. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## מודל נתונים ומפת אחסון +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -קבצי אחסון פיזיים: +Physical storage files: -- מצב ראשי: `${DATA_DIR}/db.json` (או `$XDG_CONFIG_HOME/omniroute/db.json` כאשר מוגדר, אחרת `~/.omniroute/db.json`) -- סטטיסטיקת שימוש: `${DATA_DIR}/usage.json` -- שורות יומן בקשה: `${DATA_DIR}/log.txt` -- הפעלות ניפוי באגים אופציונליות/בקשות: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## טופולוגיית פריסה +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## מיפוי מודול (קריטי להחלטה) +## Module Mapping (Decision-Critical) -### מודולי מסלול וממשק API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: ממשקי API של תאימות -- `src/app/api/v1/providers/[provider]/*`: מסלולים ייעודיים לכל ספק (צ'אט, הטבעות, תמונות) -- `src/app/api/providers*`: ספק CRUD, אימות, בדיקה -- `src/app/api/provider-nodes*`: ניהול צמתים תואם מותאם אישית -- `src/app/api/provider-models`: ניהול מודלים מותאמים אישית (CRUD) -- `src/app/api/models/catalog`: API של קטלוג דגמים מלא (כל הסוגים מקובצים לפי ספק) -- `src/app/api/oauth/*`: OAuth/קוד מכשיר זורם -- `src/app/api/keys*`: מחזור חיים של מפתח API מקומי -- `src/app/api/models/alias`: ניהול כינוי -- `src/app/api/combos*`: ניהול משולבת נפילה -- `src/app/api/pricing`: עקיפות תמחור לחישוב עלות -- `src/app/api/settings/proxy`: תצורת proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: בדיקת קישוריות פרוקסי יוצאת (POST) -- `src/app/api/usage/*`: ממשקי API של שימוש ויומנים -- `src/app/api/sync/*` + `src/app/api/cloud/*`: סנכרון ענן ועוזרים מול ענן -- `src/app/api/cli-tools/*`: כותבי/בודקים מקומיים של תצורת CLI -- `src/app/api/settings/ip-filter`: רשימת ההיתרים/רשימת חסימות של IP (GET/PUT) -- `src/app/api/settings/thinking-budget`: תצורת תקציב חשיבה (GET/PUT) -- `src/app/api/settings/system-prompt`: הודעת מערכת גלובלית (GET/PUT) -- `src/app/api/sessions`: רישום הפעלה פעיל (GET) -- `src/app/api/rate-limits`: סטטוס מגבלת תעריף לכל חשבון (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### ליבת ניתוב וביצוע +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: ניתוח בקשה, טיפול משולב, לולאה לבחירת חשבון -- `open-sse/handlers/chatCore.ts`: תרגום, שיגור מבצע, טיפול חוזר/רענון, הגדרת זרם -- `open-sse/executors/*`: התנהגות רשת ופורמט ספציפיים לספק +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### ממירי תרגום וממירי פורמטים +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: רישום מתרגמים ותזמור -- בקש מתרגמים: `open-sse/translator/request/*` -- מתרגמי תגובה: `open-sse/translator/response/*` -- קבועי פורמט: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### התמדה +### Persistence -- `src/lib/localDb.ts`: תצורה/מצב קבוע -- `src/lib/usageDb.ts`: היסטוריית שימוש ויומני בקשות מתגלגלים +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## כיסוי מנהלי ספק (דפוס אסטרטגיה) +## Provider Executor Coverage (Strategy Pattern) -לכל ספק יש מבצע מיוחד המרחיב את `BaseExecutor` (ב-`open-sse/executors/base.ts`), המספק בניית כתובות URL, בניית כותרות, ניסיון חוזר עם גיבוי אקספוננציאלי, הוקס לרענון אישורים ושיטת התזמור `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| מוציא לפועל | ספק(ים) | טיפול מיוחד | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | תצורת כתובת אתר/כותרת דינמית לכל ספק | -| `AntigravityExecutor` | Google Antigravity | מזהי פרויקט/הפעלה מותאמים אישית, ניסיון חוזר-לאחר ניתוח | -| `CodexExecutor` | OpenAI Codex | מזריק הוראות מערכת, מאלץ מאמץ חשיבה | -| `CursorExecutor` | הסמן IDE | פרוטוקול ConnectRPC, קידוד Protobuf, חתימה על בקשה באמצעות checksum | -| `GithubExecutor` | GitHub Copilot | רענון אסימון פיילוט, כותרות המחקות VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | פורמט בינארי של AWS EventStream → המרת SSE | -| `GeminiCLIExecutor` | Gemini CLI | מחזור רענון אסימון OAuth של Google | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -כל הספקים האחרים (כולל צמתים תואמים מותאמים אישית) משתמשים ב-`DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## מטריצת תאימות ספקים +## Provider Compatibility Matrix -| ספק | פורמט | Auth | זרם | לא סטרימינג | רענון אסימון | API לשימוש | -| ---------------- | ------------- | ---------------------- | ---------------- | ----------- | ------------ | ------------------- | -| קלוד | קלוד | מפתח API / OAuth | ✅ | ✅ | ✅ | ⚠️ אדמין בלבד | -| מזל תאומים | תאומים | מפתח API / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Gemini CLI | תאומים-קלי | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| אנטי כבידה | אנטי כבידה | OAuth | ✅ | ✅ | ✅ | ✅ API של מכסה מלאה | -| OpenAI | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| קודקס | openai-תגובות | OAuth | ✅ מאולץ | ❌ | ✅ | ✅ מגבלות תעריפים | -| GitHub Copilot | openai | OAuth + Token Copilot | ✅ | ✅ | ✅ | ✅ צילומי מכסה | -| סמן | סמן | סכום בדיקה מותאם אישית | ✅ | ✅ | ❌ | ❌ | -| קירו | קירו | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ מגבלות שימוש | -| קוון | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ לפי בקשה | -| iFlow | openai | OAuth (בסיסי) | ✅ | ✅ | ✅ | ⚠️ לפי בקשה | -| OpenRouter | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | קלוד | מפתח API | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| גרוק | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| מיסטרל | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| תמיהה | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| ביחד AI | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| זיקוקים AI | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| מוחין | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| קוהר | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | מפתח API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## כיסוי תרגום בפורמט +## Format Translation Coverage -פורמטי מקור שזוהו כוללים: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -פורמטי היעד כוללים: +Target formats include: -- צ'אט/תגובות של OpenAI -- קלוד -- מעטפת תאומים/תאומים-CLI/אנטי כבידה -- קירו -- סמן +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -תרגומים משתמשים ב-**OpenAI כפורמט הרכז** - כל ההמרות עוברות דרך OpenAI כאמצעי ביניים: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -תרגומים נבחרים באופן דינמי על סמך צורת מטען מקור ופורמט יעד של ספק. +Translations are selected dynamically based on source payload shape and provider target format. -שכבות עיבוד נוספות בצינור התרגום: +Additional processing layers in the translation pipeline: -- **חיטוי תגובות** - מסיר שדות לא סטנדרטיים מתגובות בפורמט OpenAI (גם סטרימינג וגם לא סטרימינג) כדי להבטיח תאימות קפדנית של SDK -- **נורמליזציה של תפקידים** - ממירה `developer` → `system` עבור יעדים שאינם OpenAI; ממזג את `system` → `user` עבור מודלים שדוחים את תפקיד המערכת (GLM, ERNIE) -- **חושב חילוץ תגים** - מנתח `...` בלוקים מתוכן לשדה `reasoning_content` -- **פלט מובנה** — ממיר את OpenAI `response_format.json_schema` ל-`responseMimeType` + `responseSchema` של Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## נקודות קצה נתמכות של ממשק API +## Supported API Endpoints -| נקודת קצה | פורמט | מטפל | -| -------------------------------------------------- | ----------------------- | ------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | קלוד הודעות | אותו מטפל (זוהה אוטומטית) | -| `POST /v1/responses` | OpenAI תגובות | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | רשימת דגמים | נתיב API | -| `POST /v1/images/generations` | OpenAI תמונות | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | רשימת דגמים | נתיב API | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | ייעודי לכל ספק עם אימות מודל | -| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | ייעודי לכל ספק עם אימות מודל | -| `POST /v1/providers/{provider}/images/generations` | OpenAI תמונות | ייעודי לכל ספק עם אימות מודל | -| `POST /v1/messages/count_tokens` | ספירת האסימונים של קלוד | נתיב API | -| `GET /v1/models` | רשימת דגמי OpenAI | מסלול API (צ'אט + הטמעה + תמונה + מודלים מותאמים אישית) | -| `GET /api/models/catalog` | קטלוג | כל הדגמים מקובצים לפי ספק + סוג | -| `POST /v1beta/models/*:streamGenerateContent` | יליד מזל תאומים | נתיב API | -| `GET/PUT/DELETE /api/settings/proxy` | תצורת פרוקסי | תצורת פרוקסי רשת | -| `POST /api/settings/proxy/test` | קישוריות פרוקסי | נקודת קצה בדיקת תקינות/קישוריות של פרוקסי | -| `GET/POST/DELETE /api/provider-models` | דגמים מותאמים אישית | ניהול מודל מותאם אישית לכל ספק | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## מטפל עוקף +## Bypass Handler -המטפל בעקיפה (`open-sse/utils/bypassHandler.ts`) מיירט בקשות "השלכה" ידועות מקלוד CLI - פינגי חימום, חילוצי כותרות וספירת אסימונים - ומחזיר **תגובה מזויפת** מבלי לצרוך אסימוני ספק במעלה הזרם. זה מופעל רק כאשר `User-Agent` מכיל `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## בקש צינור לוגר +## Request Logger Pipeline -לוגר הבקשות (`open-sse/utils/requestLogger.ts`) מספק צינור רישום באגים בן 7 שלבים, מושבת כברירת מחדל, מופעל באמצעות `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -קבצים נכתבים אל `/logs//` עבור כל הפעלת בקשה. +Files are written to `/logs//` for each request session. -## מצבי כשל וחוסן +## Failure Modes and Resilience -## 1) זמינות חשבון/ספק +## 1) Account/Provider Availability -- צינון חשבון ספק על שגיאות חולפות/שיעור/אישור -- חזרה בחשבון לפני שהבקשה נכשלה -- חזרה של מודל משולב כאשר נתיב הדגם/הספק הנוכחי מוצה +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) תפוגה של אסימון +## 2) Token Expiry -- בדוק מראש ורענן עם ניסיון חוזר עבור ספקים הניתנים לרענון -- 401/403 נסה שוב לאחר ניסיון רענון בנתיב הליבה +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) בטיחות זרם +## 3) Stream Safety -- בקר זרם מודע לניתוק -- זרם תרגום עם שטיפה של סוף זרם וטיפול `[DONE]` -- הערכת שימוש חוזרת כאשר חסרים מטא נתונים של שימוש בספק +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) השפלת סנכרון בענן +## 4) Cloud Sync Degradation -- מופיעות שגיאות סנכרון אך זמן הריצה המקומי נמשך -- למתזמן יש לוגיקה המאפשרת ניסיון חוזר, אך ביצוע תקופתי קורא כרגע לסנכרון של ניסיון יחיד כברירת מחדל +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) שלמות נתונים +## 5) Data Integrity -- העברת צורות DB/תיקון עבור מפתחות חסרים -- אמצעי הגנה לאיפוס JSON פגומים עבור localDb ו-usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## אותות תצפית ותפעול +## Observability and Operational Signals -מקורות נראות בזמן ריצה: +Runtime visibility sources: -- יומני מסוף מ-`src/sse/utils/logger.ts` -- צבירי שימוש לכל בקשה ב-`usage.json` -- יומן סטטוס בקשה טקסטואלית ב-`log.txt` -- יומני בקשה/תרגום עמוקים אופציונליים תחת `logs/` כאשר `ENABLE_REQUEST_LOGS=true` -- נקודות קצה לשימוש בלוח המחוונים (`/api/usage/*`) לצריכת ממשק משתמש +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## גבולות רגישים לביטחון +## Security-Sensitive Boundaries -- סוד JWT (`JWT_SECRET`) מאבטח אימות/חתימה של קובצי Cookie של לוח המחוונים -- יש לעקוף סיסמה ראשונית (`INITIAL_PASSWORD`, ברירת המחדל `123456`) בפריסות אמיתיות -- סוד מפתח API HMAC (`API_KEY_SECRET`) מאבטח פורמט מפתח API מקומי שנוצר -- סודות הספק (מפתחות/אסימונים של API) נשמרים ב-DB מקומי ויש להגן עליהם ברמת מערכת הקבצים -- נקודות קצה של סנכרון ענן מסתמכות על סמנטיקה של אימות מפתח API + מזהה מכונה +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## מטריצת סביבה וזמן ריצה +## Environment and Runtime Matrix -משתני סביבה בשימוש פעיל על ידי קוד: +Environment variables actively used by code: -- אפליקציה/אישור: `JWT_SECRET`, `INITIAL_PASSWORD` -- אחסון: `DATA_DIR` -- התנהגות צמתים תואמת: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- עקיפה אופציונלית של בסיס אחסון (Linux/macOS כאשר `DATA_DIR` לא מוגדר): `XDG_CONFIG_HOME` -- גיבוב אבטחה: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- רישום: `ENABLE_REQUEST_LOGS` -- סנכרון/כתובת URL בענן: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- פרוקסי יוצא: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` וגרסאות קטנות -- דגלים של תכונות SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- עוזרי פלטפורמה/זמן ריצה (לא תצורה ספציפית לאפליקציה): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## הערות אדריכליות ידועות +## Known Architectural Notes -1. `usageDb` ו`localDb` חולקים כעת את אותה מדיניות ספריית בסיס (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) עם העברת קבצים מדור קודם. -2. `/api/v1/route.ts` מחזירה רשימת מודלים סטטית ואינה מקור המודלים העיקרי המשמש את `/v1/models`. -3. לוגר הבקשות כותב כותרות/גוף מלא כאשר מופעל; התייחס לספריית היומן כרגישה. -4. התנהגות ענן תלויה ב-`NEXT_PUBLIC_BASE_URL` נכונות ובנגישות לנקודת הקצה בענן. -5. ספריית `open-sse/` מתפרסמת בתור `@omniroute/open-sse` **חבילת סביבת העבודה npm**. קוד המקור מייבא אותו באמצעות `@omniroute/open-sse/...` (נפתר על ידי Next.js `transpilePackages`). נתיבים לקובץ במסמך זה עדיין משתמשים בשם הספרייה `open-sse/` לצורך עקביות. -6. תרשימים בלוח המחוונים משתמשים ב-**Recharts** (מבוסס SVG) להדמיות ניתוח נגישות ואינטראקטיביות (תרשימי עמודות שימוש במודל, טבלאות פירוט של ספקים עם אחוזי הצלחה). -7. מבחני E2E משתמשים ב-**מחזאי** (`tests/e2e/`), מופעלים דרך `npm run test:e2e`. בדיקות יחידה משתמשות ב-**Node.js test runner** (`tests/unit/`), מופעלות דרך `npm run test:plan3`. קוד המקור תחת `src/` הוא **TypeScript** (`.ts`/`.tsx`); סביבת העבודה `open-sse/` נשארת JavaScript (`.js`). -8. דף ההגדרות מאורגן ב-5 כרטיסיות: אבטחה, ניתוב (6 אסטרטגיות גלובליות: fill-first, round-robin, p2c, אקראי, הכי פחות בשימוש, אופטימיזציה לעלות), חוסן (מגבלות קצב הניתנות לעריכה, מפסק זרם, מדיניות), AI (תקציב חשיבה, הנחיית מערכת, מטמון הנחיה), מתקדם (פרוקסי). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## רשימת אימות תפעולית +## Operational Verification Checklist -- בנה ממקור: `npm run build` -- בניית תמונת Docker: `docker build -t omniroute .` -- התחל את השירות ואמת: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- כתובת האתר של בסיס יעד CLI צריכה להיות `http://:20128/v1` כאשר `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/he/CODEBASE_DOCUMENTATION.md b/docs/i18n/he/CODEBASE_DOCUMENTATION.md index 55e69b19ad..303880c198 100644 --- a/docs/i18n/he/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/he/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — תיעוד בסיס קוד +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> מדריך מקיף וידידותי למתחילים לנתב ה-Proxy **omniroute** מרובה ספקי AI. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. מהו omnirroute? +## 1. What Is omniroute? -omniroute הוא **נתב פרוקסי** שיושב בין לקוחות AI (קלוד CLI, Codex, Cursor IDE וכו') וספקי AI (Anthropic, Google, OpenAI, AWS, GitHub וכו'). זה פותר בעיה אחת גדולה: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **לקוחות AI שונים מדברים "שפות" שונות (פורמטים של API), וספקי AI שונים מצפים גם ל"שפות" שונות.** omniroute מתרגם ביניהם באופן אוטומטי. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -תחשוב על זה כמו מתרגם אוניברסלי באו"ם - כל נציג יכול לדבר כל שפה, והמתרגם ממיר אותו עבור כל נציג אחר. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. סקירת אדריכלות +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### עקרון ליבה: תרגום רכזת ודיבור +### Core Principle: Hub-and-Spoke Translation -כל תרגום הפורמט עובר דרך **פורמט OpenAI כמרכז**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -המשמעות היא שאתה צריך רק **N מתרגמים** (אחד לכל פורמט) במקום **N²** (כל זוג). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. מבנה הפרויקט +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. פירוט מודול אחר מודול +## 4. Module-by-Module Breakdown ### 4.1 Config (`open-sse/config/`) -**מקור האמת היחיד** לכל תצורת הספקים. +The **single source of truth** for all provider configuration. -| קובץ | מטרה | -| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | אובייקט `PROVIDERS` עם כתובות URL בסיסיות, אישורי OAuth (ברירת מחדל), כותרות והנחיות מערכת ברירת מחדל עבור כל ספק. מגדיר גם את `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` ו`SKIP_PATTERNS`. | -| `credentialLoader.ts` | טוען אישורים חיצוניים מ-`data/provider-credentials.json` וממזג אותם על פני ברירות המחדל המקודדות ב-`PROVIDERS`. שומר סודות מחוץ לשליטת המקור תוך שמירה על תאימות לאחור. | -| `providerModels.ts` | רישום מודלים מרכזי: כינויים של ספקי מפות → מזהי מודל. פונקציות כמו `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | הוראות מערכת שהוזרקו לבקשות Codex (אילוצי עריכה, כללי ארגז חול, מדיניות אישור). | -| `defaultThinkingSignature.ts` | ברירת המחדל של חתימות "חשיבה" עבור דגמי קלוד וג'מיני. | -| `ollamaModels.ts` | הגדרת סכמה למודלים מקומיים של אולמה (שם, גודל, משפחה, כימות). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### זרימת טעינת אישורים +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 מבצעים (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -מבצעים עוטפים **היגיון ספציפי לספק** באמצעות **דפוס האסטרטגיה**. כל מבצע עוקף את שיטות הבסיס לפי הצורך. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| מוציא לפועל | ספק | התמחויות מפתח | -| ---------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | בסיס תקציר: בניית כתובת URL, כותרות, הגיון ניסיון חוזר, רענון אישורים | -| `default.ts` | קלוד, ג'מיני, OpenAI, GLM, Kimi, MiniMax | רענון אסימון OAuth כללי עבור ספקים סטנדרטיים | -| `antigravity.ts` | Google Cloud Code | יצירת מזהה פרויקט/הפעלה, ניתוק רב של כתובות אתרים, ניסיון חוזר מותאם אישית לנתח מהודעות שגיאה ("איפוס לאחר 2h7m23s") | -| `cursor.ts` | הסמן IDE | **המורכבים ביותר**: SHA-256 checksum auth, קידוד בקשת Protobuf, EventStream בינארי → ניתוח תגובת SSE | -| `codex.ts` | OpenAI Codex | מזריק הוראות מערכת, מנהל רמות חשיבה, מסיר פרמטרים לא נתמכים | -| `gemini-cli.ts` | Google Gemini CLI | בניית כתובת אתר מותאמת אישית (`streamGenerateContent`), רענון אסימון OAuth של Google | -| `github.ts` | GitHub Copilot | מערכת אסימון כפול (GitHub OAuth + Token Copilot), חיקוי כותרת VSCode | -| `kiro.ts` | AWS CodeWhisperer | ניתוח בינארי של AWS EventStream, מסגרות אירועי AMZN, הערכת אסימון | -| `index.ts` | — | מפעל: שם ספק מפות → מחלקת executor, עם ברירת מחדל | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 מטפלים (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**שכבת התזמור** - מתאמת תרגום, ביצוע, סטרימינג וטיפול בשגיאות. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| קובץ | מטרה | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **מתזמר מרכזי** (~600 שורות). מטפל במחזור החיים המלא של הבקשה: זיהוי פורמט ← תרגום ← שליחת מבצע ← תגובת סטרימינג/לא זרימה ← רענון אסימון ← טיפול בשגיאות ← רישום שימוש. | -| `responsesHandler.ts` | מתאם עבור ה-API של תגובות של OpenAI: ממיר פורמט תגובות ← השלמות צ'אט ← שולח ל-`chatCore` → ממיר SSE בחזרה לפורמט תגובות. | -| `embeddings.ts` | מטפל ביצירת הטבעה: פותר מודל הטמעה → ספק, שולח לספק API, מחזיר תגובת הטבעה תואמת OpenAI. תומך ב-6 ספקים ומעלה. | -| `imageGeneration.ts` | מטפל בהפקת תמונה: פותר את מודל התמונה → ספק, תומך במצבי OpenAI, תמונת תאומים (אנטי כבידה) ו-Nebius. מחזירה תמונות base64 או כתובת URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### מחזור חיים של בקשה (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 שירותים (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -היגיון עסקי התומך במטפלים ובמבצעים. +Business logic that supports the handlers and executors. -| קובץ | מטרה | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `provider.ts` | **זיהוי פורמטים** (`detectFormat`): מנתח את מבנה גוף הבקשה כדי לזהות פורמטים של קלוד/OpenAI/Gemini/Antigravity/Responses (כולל `max_tokens` היוריסטיקה עבור קלוד). כמו כן: בניית כתובת URL, בניית כותרות, נורמליזציה של תצורת חשיבה. תומך בספקים דינמיים של `openai-compatible-*` ו`anthropic-compatible-*`. | -| `model.ts` | ניתוח מחרוזת מודל (`claude/model-name` → `{provider: "claude", model: "model-name"}`), רזולוציית כינוי עם זיהוי התנגשות, חיטוי קלט (דוחה חציית נתיב/תווים בקרה), ורזולוציית מידע על דגם עם תמיכה ב-Getter כינוי אסינכרון. | -| `accountFallback.ts` | טיפול במגבלת קצב: השבתה אקספוננציאלית (1 שניות → 2 שניות → 4 שניות → מקסימום 2 דקות), ניהול התקררות חשבונות, סיווג שגיאות (אשר השגיאות מעוררות נפילה לעומת לא). | -| `tokenRefresh.ts` | רענון אסימון OAuth עבור **כל ספק**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). כולל מטמון הבטחה למניעת כפילויות במהלך הטיסה וניסיון חוזר עם השבתה אקספוננציאלית. | -| `combo.ts` | **דגמי משולבים**: רשתות של דגמי חלודה. אם דגם A נכשל עם שגיאה מתאימה, נסה את דגם B, ולאחר מכן C וכו'. מחזירה קודי סטטוס בפועל במעלה הזרם. | -| `usage.ts` | שואב נתוני מכסה/שימוש ממשקי API של ספקים (מכסות GitHub Copilot, מכסות של מודלים נגד כבידה, מגבלות תעריף Codex, תקלות שימוש ב-Kiro, הגדרות קלוד). | -| `accountSelector.ts` | בחירת חשבון חכמה עם אלגוריתם ניקוד: לוקח בחשבון עדיפות, מצב בריאותי, מיקום סיבובי ומצב צינון כדי לבחור את החשבון האופטימלי עבור כל בקשה. | -| `contextManager.ts` | ניהול מחזור החיים של בקשת הקשר: יוצר ועוקב אחר אובייקטי הקשר לפי בקשה עם מטא נתונים (מזהה בקשה, חותמות זמן, מידע על ספק) לצורך ניפוי באגים ורישום. | -| `ipFilter.ts` | בקרת גישה מבוססת IP: תומך במצבי רשימת היתרים ורשימת חסימה. מאמת את ה-IP של הלקוח מול כללים מוגדרים לפני עיבוד בקשות API. | -| `sessionManager.ts` | מעקב אחר פעילויות עם טביעת אצבע של לקוח: עוקב אחר פעילויות פעילות באמצעות מזהי לקוח מגובבים, עוקב אחר ספירת בקשות ומספק מדדי הפעלה. | -| `signatureCache.ts` | מטמון ביטול כפילויות מבוסס בקשת חתימה: מונע בקשות כפולות על ידי שמירה במטמון של חתימות בקשות אחרונות והחזרת תגובות שמור עבור בקשות זהות בתוך חלון זמן. | -| `systemPrompt.ts` | הזרקת הנחיה עולמית למערכת: הוספה או הוספה של הנחיה מערכת הניתנת להגדרה לכל הבקשות, עם טיפול בתאימות לכל ספק. | -| `thinkingBudget.ts` | ניהול תקציב אסימון נימוק: תומך במצבי מעבר, אוטומטי (תצורת חשיבה רצועת), מותאם אישית (תקציב קבוע) ומצבי הסתגלות (בגודל מורכבות) לשליטה באסימוני חשיבה/היגיון. | -| `wildcardRouter.ts` | ניתוב דפוסי מודל תווים כלליים: פותר דפוסי תווים כלליים (למשל, `*/claude-*`) לצמדי ספק/מודל קונקרטיים על סמך זמינות ועדיפות. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### ביטול כפילויות של רענון אסימון +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### שרשרת דגם משולבת +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 מתרגם (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) The **format translation engine** using a self-registering plugin system. -#### ארכיטקטורה +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| מדריך | קבצים | תיאור | -| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 מתרגמים | המרת גופי בקשה בין פורמטים. כל קובץ נרשם בעצמו באמצעות `register(from, to, fn)` בייבוא. | -| `response/` | 7 מתרגמים | המר נתחי תגובה זורמת בין פורמטים. מטפל בסוגי אירועי SSE, בלוקי חשיבה, קריאות לכלים. | -| `helpers/` | 6 עוזרים | כלי עזר משותפים: `claudeHelper` (חילוץ הנחיות מערכת, תצורת חשיבה), `geminiHelper` (מיפוי חלקים/תוכן), `openaiHelper` (סינון פורמט), `toolCallHelper` (יצירת מזהה, הזרקת תגובה חסרה), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | מנוע תרגום: `translateRequest()`, `translateResponse()`, הנהלת מדינה, רישום. | -| `formats.ts` | — | קבועי פורמט: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### עיצוב מפתח: תוספים לרישום עצמי +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -397,17 +397,17 @@ import "./request/claude-to-openai.js"; // ← self-registers ### 4.6 Utils (`open-sse/utils/`) -| קובץ | מטרה | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | בניית תגובת שגיאה (פורמט תואם OpenAI), ניתוח שגיאות במעלה הזרם, חילוץ בזמן ניסיון חוזר נגד כבידה מהודעות שגיאה, הזרמת שגיאות SSE. | -| `stream.ts` | **SSE Transform Stream** - צינור הסטרימינג המרכזי. שני מצבים: `TRANSLATE` (תרגום בפורמט מלא) ו-`PASSTHROUGH` (נרמל + חילוץ שימוש). מטפל בחציצה של נתחים, הערכת שימוש, מעקב אחר אורך תוכן. מופעי מקודד/מפענחים לכל זרם נמנעים ממצב משותף. | -| `streamHelpers.ts` | כלי עזר SSE ברמה נמוכה: `parseSSELine` (סובלנות לרווחים לבנים), `hasValuableContent` (מסננים נתחים ריקים עבור OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (ניקוי SSE-TOKEN_103\*\* המודע לפורמט עם ). | -| `usageTracking.ts` | חילוץ שימוש באסימונים מכל פורמט (Claude/OpenAI/Gemini/Responses), אומדן עם יחסי תווים/הודעה נפרדים של כלי/הודעה, הוספת חיץ (מרווח בטיחות של 2000 אסימונים), סינון שדות ספציפי לפורמט, רישום מסוף עם צבעי ANSI. | -| `requestLogger.ts` | רישום בקשות מבוסס קבצים (הצטרפות דרך `ENABLE_REQUEST_LOGS=true`). יוצר תיקיות הפעלה עם קבצים ממוספרים: `1_req_client.json` → `7_res_client.txt`. כל הקלט/פלט הוא אסינכרון (אש ושכח). מסכה כותרות רגישות. | -| `bypassHandler.ts` | מיירט דפוסים ספציפיים של קלוד CLI (חילוץ כותרת, חימום, ספירה) ומחזיר תגובות מזויפות מבלי להתקשר לאף ספק. תומך גם בסטרימינג וגם לא בסטרימינג. מוגבל בכוונה להיקף קלוד CLI. | -| `networkProxy.ts` | פותר כתובת URL של proxy יוצאת עבור ספק נתון עם עדיפות: תצורה ספציפית לספק → תצורה גלובלית → משתני סביבה (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). תומך בהחרגות `NO_PROXY`. תצורת מטמון עבור שנות ה-30. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### צינור הזרמת SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### בקש מבנה הפעלה של לוגר +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 שכבת יישומים (`src/`) +### 4.7 Application Layer (`src/`) -| מדריך | מטרה | -| ------------- | ----------------------------------------------------------------------------------- | -| `src/app/` | ממשק משתמש אינטרנט, מסלולי API, תוכנת ביניים אקספרס, מטפלים בהתקשרות חוזרת של OAuth | -| `src/lib/` | גישה למסד נתונים (`localDb.ts`, `usageDb.ts`), אימות, משותף | -| `src/mitm/` | כלי פרוקסי של אדם-באמצע ליירוט תעבורת ספקים | -| `src/models/` | הגדרות מודל מסד נתונים | -| `src/shared/` | עוטפים סביב פונקציות Open-sse (ספק, זרם, שגיאה וכו') | -| `src/sse/` | מטפלי נקודות קצה SSE המחוברים את ספריית ה-Open-sse לנתיבי Express | -| `src/store/` | ניהול מצב יישומים | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### נתיבי API בולטים +#### Notable API Routes -| מסלול | שיטות | מטרה | -| --------------------------------------------- | -------------- | -------------------------------------------------------------------------- | -| `/api/provider-models` | קבל/פרסם/מחק | CRUD עבור דגמים מותאמים אישית לכל ספק | -| `/api/models/catalog` | קבל | קטלוג מצטבר של כל הדגמים (צ'אט, הטמעה, תמונה, מותאם אישית) מקובצים לפי ספק | -| `/api/settings/proxy` | GET/PUT/DELETE | תצורת proxy יוצאת היררכית (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | פוסט | מאמת את קישוריות ה-proxy ומחזירה IP/השהייה ציבורית | -| `/v1/providers/[provider]/chat/completions` | פוסט | השלמות צ'אט ייעודיות לכל ספק עם אימות מודל | -| `/v1/providers/[provider]/embeddings` | פוסט | הטמעות ייעודיות לכל ספק עם אימות מודל | -| `/v1/providers/[provider]/images/generations` | פוסט | יצירת תמונה ייעודית לכל ספק עם אימות מודל | -| `/api/settings/ip-filter` | GET/PUT | ניהול רשימת הרשאות IP/רשימת חסימה | -| `/api/settings/thinking-budget` | GET/PUT | תצורת תקציב אסימון נימוק (מעבר/אוטומטי/מותאם אישית/מותאם) | -| `/api/settings/system-prompt` | GET/PUT | הזרקה מהירה של מערכת גלובלית לכל הבקשות | -| `/api/sessions` | קבל | מעקב ומדדי הפעלה פעילים | -| `/api/rate-limits` | קבל | סטטוס מגבלת תעריף לכל חשבון | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. דפוסי עיצוב מפתח +## 5. Key Design Patterns -### 5.1 תרגום רכזת ודיבור +### 5.1 Hub-and-Spoke Translation -כל הפורמטים מתורגמים באמצעות **פורמט OpenAI כמרכז**. הוספת ספק חדש דורשת רק כתיבת **זוג אחד** של מתרגמים (ל/מ OpenAI), לא N זוגות. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 דפוס אסטרטגיית מבצעים +### 5.2 Executor Strategy Pattern -לכל ספק יש מחלקת מבצעים ייעודית שיורשת מ`BaseExecutor`. המפעל ב`executors/index.ts` בוחר את המתאים בזמן הריצה. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 מערכת פלאגין לרישום עצמי +### 5.3 Self-Registering Plugin System -מודולי מתרגם רושמים את עצמם בייבוא דרך `register()`. הוספת מתרגם חדש היא רק יצירת קובץ ויבואו. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 חזרה בחשבון עם גיבוי אקספוננציאלי +### 5.4 Account Fallback with Exponential Backoff -כאשר ספק מחזיר 429/401/500, המערכת יכולה לעבור לחשבון הבא, תוך הפעלת צינון אקספוננציאלי (1s → 2s → 4s → max 2mins). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### שרשראות דגם 5.5 משולבות +### 5.5 Combo Model Chains -"קומבו" מקבץ `provider/model` מחרוזות מרובות. אם הראשון נכשל, חזור אל הבא באופן אוטומטי. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 תרגום סטרימינג ממלכתי +### 5.6 Stateful Streaming Translation -תרגום תגובה שומר על מצב על פני נתחי SSE (מעקב אחר בלוק חשיבה, צבירת קריאות לכלי, אינדקס של חסימות תוכן) באמצעות מנגנון `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 מאגר בטיחות לשימוש +### 5.7 Usage Safety Buffer -מאגר של 2000 אסימון נוסף לשימוש המדווח כדי למנוע מלקוחות להגיע למגבלות חלונות ההקשר עקב תקורה מהנחיות מערכת ותרגום פורמטים. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. פורמטים נתמכים +## 6. Supported Formats -| פורמט | כיוון | מזהה | -| --------------------- | ---------- | ------------------ | -| השלמות צ'אט של OpenAI | מקור + יעד | `openai` | -| OpenAI Responses API | מקור + יעד | `openai-responses` | -| האנתרופי קלוד | מקור + יעד | `claude` | -| Google Gemini | מקור + יעד | `gemini` | -| Google Gemini CLI | היעד בלבד | `gemini-cli` | -| אנטי כבידה | מקור + יעד | `antigravity` | -| AWS Kiro | היעד בלבד | `kiro` | -| סמן | היעד בלבד | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. ספקים נתמכים +## 7. Supported Providers -| ספק | שיטת אישור | מוציא לפועל | הערות מפתח | -| ------------------------ | --------------------- | ----------- | ---------------------------------------------- | -| האנתרופית קלוד | מפתח API או OAuth | ברירת מחדל | משתמש בכותרת `x-api-key` | -| Google Gemini | מפתח API או OAuth | ברירת מחדל | משתמש בכותרת `x-goog-api-key` | -| Google Gemini CLI | OAuth | GeminiCLI | משתמש בנקודת קצה `streamGenerateContent` | -| אנטי כבידה | OAuth | אנטי כבידה | ניתוק רב כתובות אתרים, ניסיון חוזר מותאם אישית | -| OpenAI | מפתח API | ברירת מחדל | אישור נושא תקן | -| קודקס | OAuth | קודקס | מזריק הוראות מערכת, מנהל חשיבה | -| GitHub Copilot | OAuth + אסימון פיילוט | Github | אסימון כפול, מחקה כותרת VSCode | -| קירו (AWS) | AWS SSO OIDC או חברתי | קירו | ניתוח EventStream בינארי | -| הסמן IDE | Checksum Auth | סמן | קידוד פרוטובוף, סיכומי ביקורת SHA-256 | -| קוון | OAuth | ברירת מחדל | אישור רגיל | -| iFlow | OAuth (בסיסי + נושא) | ברירת מחדל | כותרת אישור כפולה | -| OpenRouter | מפתח API | ברירת מחדל | אישור נושא תקן | -| GLM, Kimi, MiniMax | מפתח API | ברירת מחדל | תואם קלוד, השתמש ב-`x-api-key` | -| `openai-compatible-*` | מפתח API | ברירת מחדל | דינמי: כל נקודת קצה תואמת OpenAI | -| `anthropic-compatible-*` | מפתח API | ברירת מחדל | דינמי: כל נקודת קצה תואמת קלוד | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. סיכום זרימת נתונים +## 8. Data Flow Summary -### בקשת סטרימינג +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### בקשה ללא סטרימינג +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### זרימה עוקפת (קלוד CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/he/FEATURES.md b/docs/i18n/he/FEATURES.md index 92062d701e..82cc73b67b 100644 --- a/docs/i18n/he/FEATURES.md +++ b/docs/i18n/he/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — גלריית תכונות לוח המחוונים +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -מדריך חזותי לכל חלק בלוח המחוונים של OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 ספקים +## 🔌 Providers -נהל חיבורי ספקי AI: ספקי OAuth (Claude Code, Codex, Gemini CLI), ספקי מפתח API (Groq, DeepSeek, OpenRouter), וספקים חינמיים (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 שילובים +## 🎨 Combos -צור שילובי ניתוב מודלים עם 6 אסטרטגיות: מילוי ראשון, סיבוב סיבוב, כוח משתי בחירות, אקראי, פחות בשימוש ואופטימיזציה לעלות. כל משולבת שרשרת דגמים מרובים עם נפילה אוטומטית. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 אנליטיקה +## 📊 Analytics -ניתוח שימוש מקיף עם צריכת אסימונים, הערכות עלויות, מפות חום של פעילות, תרשימי הפצה שבועיים ופירוטים לכל ספק. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 בריאות המערכת +## 🏥 System Health -ניטור בזמן אמת: זמן פעולה, זיכרון, גרסה, אחוזי חביון (p50/p95/p99), סטטיסטיקות מטמון ומצבי מפסק זרם של ספק. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 מגרש משחקים למתרגמים +## 🔧 Translator Playground -ארבעה מצבים לאיתור באגים בתרגומי API: **Playground** (ממיר פורמטים), **Chat Tester** (בקשות חיות), **Test Bench** (בדיקות אצווה), ו**Live Monitor** (סטרימינג בזמן אמת). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ הגדרות +## 🎮 Model Playground _(v2.0.9+)_ -הגדרות כלליות, אחסון מערכת, ניהול גיבוי (ייצוא/ייבוא מסד נתונים), מראה (מצב כהה/בהיר), אבטחה (כולל הגנת נקודות קצה API וחסימת ספקים מותאמים אישית), ניתוב, חוסן ותצורה מתקדמת. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 כלי CLI +## 🔧 CLI Tools -תצורה בלחיצה אחת לכלי קידוד AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code ו-Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 יומני בקשות +## 🤖 CLI Agents _(v2.0.11+)_ -רישום בקשות בזמן אמת עם סינון לפי ספק, דגם, חשבון ומפתח API. מציג קודי סטטוס, שימוש באסימונים, זמן אחזור ופרטי תגובה. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 נקודת קצה של ממשק API +## 🌐 API Endpoint -נקודת הקצה המאוחדת של ה-API שלך עם פירוט יכולות: השלמות צ'אט, הטמעות, יצירת תמונות, דירוג מחדש, תמלול אודיו ומפתחות API רשומים. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/he/TROUBLESHOOTING.md b/docs/i18n/he/TROUBLESHOOTING.md index 874e7e384f..120092d63c 100644 --- a/docs/i18n/he/TROUBLESHOOTING.md +++ b/docs/i18n/he/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# פתרון בעיות +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -בעיות ופתרונות נפוצים עבור OmniRoute. +Common problems and solutions for OmniRoute. --- -## תיקונים מהירים +## Quick Fixes -| בעיה | פתרון | -| ------------------------------ | ---------------------------------------------------------------- | -| הכניסה הראשונה לא עובדת | סמן `INITIAL_PASSWORD` ב-`.env` (ברירת מחדל: `123456`) | -| לוח המחוונים נפתח ביציאה שגויה | הגדר `PORT=20128` ו`NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| אין יומני בקשות תחת `logs/` | סט `ENABLE_REQUEST_LOGS=true` | -| EACCES: הרשאה נדחתה | הגדר את `DATA_DIR=/path/to/writable/dir` לעקוף את `~/.omniroute` | -| אסטרטגיית ניתוב לא שומרת | עדכון לגרסה 1.4.11+ (תיקון סכמת Zod עבור התמדה בהגדרות) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## בעיות עם ספקים +## Provider Issues -### "מודל השפה לא סיפק הודעות" +### "Language model did not provide messages" -**סיבה:** מיצתה מכסת הספקים. +**Cause:** Provider quota exhausted. -**תיקון:** +**Fix:** -1. בדוק את עוקב המכסות של לוח המחוונים -2. השתמשו בשילוב עם שכבות נפילה -3. עבור לדרג זול/חינם +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### הגבלת תעריפים +### Rate Limiting -**סיבה:** מיצתה מכסת המנויים. +**Cause:** Subscription quota exhausted. -**תיקון:** +**Fix:** -- הוסף חזרה: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- השתמש ב-GLM/MiniMax כגיבוי זול +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### אסימון OAuth פג +### OAuth Token Expired -OmniRoute מרענן אוטומטית אסימונים. אם הבעיות נמשכות: +OmniRoute auto-refreshes tokens. If issues persist: -1. לוח מחוונים ← ספק ← התחבר מחדש -2. מחק והוסף מחדש את חיבור הספק +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## בעיות בענן +## Cloud Issues -### שגיאות סנכרון בענן +### Cloud Sync Errors -1. אמת `BASE_URL` נקודות למופע הריצה שלך (לדוגמה, `http://localhost:20128`) -2. אמת `CLOUD_URL` נקודות לנקודת הקצה שלך בענן (לדוגמה, `https://omniroute.dev`) -3. שמור על ערכי `NEXT_PUBLIC_*` מיושרים עם ערכי צד השרת +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### ענן `stream=false` מחזיר 500 +### Cloud `stream=false` Returns 500 -**סימפטום:** `Unexpected token 'd'...` בנקודת קצה בענן עבור שיחות שאינן זורמות. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**סיבה:** Upstream מחזיר מטען SSE בזמן שהלקוח מצפה ל-JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**פתרון לעקיפת הבעיה:** השתמש ב-`stream=true` לשיחות ישירות בענן. זמן ריצה מקומי כולל SSE → JSON fallback. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### ענן אומר מחובר אבל "מפתח API לא חוקי" +### Cloud Says Connected but "Invalid API key" -1. צור מפתח חדש מלוח המחוונים המקומי (`/api/keys`) -2. הפעל סנכרון ענן: הפעל ענן ← סנכרן עכשיו -3. מפתחות ישנים/לא מסונכרנים עדיין יכולים להחזיר `401` בענן +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## בעיות דוקר +## Docker Issues -### כלי CLI מציג לא מותקן +### CLI Tool Shows Not Installed -1. בדוק את שדות זמן הריצה: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. עבור מצב נייד: השתמש ביעד תמונה `runner-cli` (CLI מצרפים) -3. עבור מצב הרכבה מארח: הגדר את `CLI_EXTRA_PATHS` ואת ספריית סל המארח כקריאה בלבד -4. אם `installed=true` ו`runnable=false`: בינארי נמצא אך נכשל בבדיקת הבריאות +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### אימות מהיר של זמן ריצה +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## בעיות בעלויות +## Cost Issues -### עלויות גבוהות +### High Costs -1. בדוק את סטטיסטיקת השימוש בלוח המחוונים ← שימוש -2. החלף את הדגם הראשי ל-GLM/MiniMax -3. השתמש בשכבה חינמית (Gemini CLI, iFlow) למשימות לא קריטיות -4. הגדר תקציבי עלויות לכל מפתח API: לוח מחוונים ← מפתחות API ← תקציב +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## איתור באגים +## Debugging -### אפשר יומני בקשות +### Enable Request Logs -הגדר את `ENABLE_REQUEST_LOGS=true` בקובץ `.env` שלך. יומנים מופיעים תחת ספריית `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### בדוק את תקינות הספק +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### אחסון בזמן ריצה +### Runtime Storage -- מצב ראשי: `${DATA_DIR}/db.json` (ספקים, שילובים, כינויים, מפתחות, הגדרות) -- שימוש: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- יומני בקשות: `/logs/...` (כאשר `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## בעיות מפסקים +## Circuit Breaker Issues -### הספק תקוע במצב OPEN +### Provider stuck in OPEN state -כאשר מפסק החשמל של ספק פתוח, הבקשות נחסמות עד לפקיעת הקירור. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**תיקון:** +**Fix:** -1. עבור אל **לוח מחוונים ← הגדרות ← חוסן** -2. בדוק את כרטיס המפסק עבור הספק המושפע -3. לחץ על **אפס הכל** כדי לנקות את כל המפסקים, או המתן עד שתוקף הקירור יפוג -4. ודא שהספק אכן זמין לפני האיפוס +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### הספק ממשיך להדליק את המפסק +### Provider keeps tripping the circuit breaker -אם ספק נכנס שוב ושוב למצב OPEN: +If a provider repeatedly enters OPEN state: -1. סמן את **לוח המחוונים ← תקינות ← תקינות הספק** עבור דפוס הכשל -2. עבור אל **הגדרות ← חוסן ← פרופילי ספקים** והגדל את סף הכשל -3. בדוק אם הספק שינה מגבלות API או שהוא דורש אימות מחדש -4. סקירת טלמטריית חביון - זמן אחזור גבוה עלול לגרום לכשלים מבוססי זמן קצוב +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## בעיות בתמלול אודיו +## Audio Transcription Issues -### שגיאה "מודל לא נתמך". +### "Unsupported model" error -- ודא שאתה משתמש בקידומת הנכונה: `deepgram/nova-3` או `assemblyai/best` -- ודא שהספק מחובר ב-**לוח מחוונים → ספקים** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### התמלול מחזיר ריק או נכשל +### Transcription returns empty or fails -- בדוק פורמטי שמע נתמכים: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- ודא שגודל הקובץ נמצא בגבולות הספק (בדרך כלל < 25MB) -- בדוק את תוקף מפתח ה-API של ספק בכרטיס הספק +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## ניפוי באגים של מתרגם +## Translator Debugging -השתמש ב**לוח המחוונים ← מתרגם** כדי לנפות באגים בבעיות תרגום בפורמט: +Use **Dashboard → Translator** to debug format translation issues: -| מצב | מתי להשתמש | -| --------------- | ------------------------------------------------------------------------------ | -| **מגרש משחקים** | השווה פורמטים של קלט/פלט זה לצד זה - הדבק בקשה נכשלת כדי לראות איך היא מתורגמת | -| **בודק צ'אט** | שלח הודעות חיות ובדוק את מטען הבקשה/תגובה המלא כולל כותרות | -| **ספסל מבחן** | הפעל בדיקות אצווה על פני שילובי פורמטים כדי למצוא אילו תרגומים מקולקלים | -| **שידור חי** | צפה בזרם הבקשות בזמן אמת כדי לתפוס בעיות תרגום לסירוגין | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### בעיות פורמט נפוצות +### Common format issues -- **תגי חשיבה לא מופיעים** — בדוק אם ספק היעד תומך בחשיבה ובהגדרת תקציב החשיבה -- **הורדת שיחות הכלים** - תרגומי פורמט מסוימים עשויים להסיר שדות שאינם נתמכים; לאמת במצב Playground -- **הנחיית מערכת חסרה** - קלוד וג'מיני מטפלים בהנחיות המערכת בצורה שונה; בדוק את פלט התרגום -- **SDK מחזיר מחרוזת גולמית במקום אובייקט** - תוקן בגרסה 1.1.0: ניקוי התגובה מסיר כעת שדות לא סטנדרטיים (`x_groq`, `usage_breakdown` וכו') שגורמים לכשלי אימות של OpenAI SDK Pydantic -- **GLM/ERNIE דוחה תפקיד `system`** - תוקן בגרסה 1.1.0: מנרמל תפקידים ממזג אוטומטית הודעות מערכת להודעות משתמש עבור דגמים לא תואמים -- **`developer` תפקיד לא מזוהה** - תוקן בגרסה 1.1.0: הומר אוטומטית ל`system` עבור ספקים שאינם OpenAI -- **`json_schema` לא עובד עם Gemini** - תוקן בגרסה 1.1.0: `response_format` הומר כעת ל-`responseMimeType` + `responseSchema` של Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## הגדרות חוסן +## Resilience Settings -### מגבלת שיעור אוטומטי לא מופעלת +### Auto rate-limit not triggering -- הגבלת תעריף אוטומטי חלה רק על ספקי מפתח API (לא OAuth/מינוי) -- ודא של **הגדרות ← חוסן ← פרופילי ספקים** מופעלת הגבלת תעריף אוטומטי -- בדוק אם הספק מחזיר `429` קודי סטטוס או כותרות `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### כוונון גיבוי אקספוננציאלי +### Tuning exponential backoff -פרופילי ספקים תומכים בהגדרות הבאות: +Provider profiles support these settings: -- **השהיית בסיס** - זמן המתנה ראשוני לאחר הכשל הראשון (ברירת מחדל: 1 שניות) -- **עיכוב מרבי** - מכסת זמן המתנה מקסימלית (ברירת מחדל: 30 שניות) -- **מכפיל** - כמה להגדיל את העיכוב לכל כשל רצוף (ברירת מחדל: פי 2) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### עדר נגד רעמים +### Anti-thundering herd -כאשר בקשות בו-זמניות רבות פוגעות בספק מוגבל בקצב, OmniRoute משתמשת ב-mutex + הגבלת קצב אוטומטית כדי להדגיש בקשות ולמנוע כשלים מדורגים. זה אוטומטי עבור ספקי מפתחות API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## עדיין תקוע? +## Optional RAG / LLM failure taxonomy (16 problems) -- **בעיות GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **אדריכלות**: ראה [link](ARCHITECTURE.md) לפרטים פנימיים -- **הפניה ל-API**: ראה [link](API_REFERENCE.md) עבור כל נקודות הקצה -- **לוח מחוונים לבריאות**: בדוק את **לוח מחוונים ← בריאות** למצב מערכת בזמן אמת -- **מתרגם**: השתמש ב-**לוח מחוונים ← מתרגם** כדי לנפות באגים בפורמט +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/he/USER_GUIDE.md b/docs/i18n/he/USER_GUIDE.md index f8b89871fb..5a043224df 100644 --- a/docs/i18n/he/USER_GUIDE.md +++ b/docs/i18n/he/USER_GUIDE.md @@ -1,12 +1,12 @@ -# מדריך למשתמש +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -מדריך שלם להגדרת ספקים, יצירת שילובים, שילוב כלי CLI ופריסה של OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## תוכן העניינים +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 תמחור במבט חטוף +## 💰 Pricing at a Glance -| שכבה | ספק | עלות | איפוס מכסה | הטוב ביותר עבור | -| --------------- | ---------------- | --------------- | ------------------------ | ----------------------------- | -| **💳 מנוי** | קלוד קוד (פרו) | 20 דולר לחודש | 5 שעות + שבועי | כבר נרשמת | -| | קודקס (פלוס/פרו) | $20-200 לחודש | 5 שעות + שבועי | משתמשי OpenAI | -| | Gemini CLI | **חינם** | 180K/Mo + 1K/יום | כֹּל אֶחָד! | -| | GitHub Copilot | $10-19 לחודש | חודשי | משתמשי GitHub | -| **🔑 מפתח API** | DeepSeek | תשלום לפי שימוש | אין | נימוק זול | -| | גרוק | תשלום לפי שימוש | אין | הסקה מהירה במיוחד | -| | xAI (Grok) | תשלום לפי שימוש | אין | גרוק 4 הנמקה | -| | מיסטרל | תשלום לפי שימוש | אין | דגמים המתארחים באיחוד האירופי | -| | תמיהה | תשלום לפי שימוש | אין | חיפוש מוגדל | -| | ביחד AI | תשלום לפי שימוש | אין | מודלים של קוד פתוח | -| | זיקוקים AI | תשלום לפי שימוש | אין | תמונות מהיר FLUX | -| | מוחין | תשלום לפי שימוש | אין | מהירות בקנה מידה רקיק | -| | קוהר | תשלום לפי שימוש | אין | פקודה R+ RAG | -| | NVIDIA NIM | תשלום לפי שימוש | אין | דגמים ארגוניים | -| **💰 זול** | GLM-4.7 | $0.6/1 מיליון | כל יום 10:00 | גיבוי תקציבי | -| | MiniMax M2.1 | $0.2/1 מיליון | גלגול של 5 שעות | האפשרות הזולה ביותר | -| | קימי K2 | 9 $ לחודש דירה | 10 מיליון אסימונים לחודש | עלות צפויה | -| **🆓 חינם** | iFlow | $0 | ללא הגבלה | 8 דגמים חינם | -| | קוון | $0 | ללא הגבלה | 3 דגמים חינם | -| | קירו | $0 | ללא הגבלה | קלוד חופשי | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 טיפ מקצועי:** התחל עם Gemini CLI (180K חינם/חודש) + שילוב של iFlow (ללא הגבלה בחינם) = עלות של $0! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 מקרי שימוש +## 🎯 Use Cases -### מקרה 1: "יש לי מנוי לקלוד פרו" +### Case 1: "I have Claude Pro subscription" -**בעיה:** תוקף המכסה פג ללא שימוש, מגבלות תעריף במהלך קידוד כבד +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### מקרה 2: "אני רוצה עלות אפס" +### Case 2: "I want zero cost" -**בעיה:** לא יכול להרשות לעצמו מנויים, צריך קידוד AI אמין +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### מקרה 3: "אני צריך קידוד 24/7, ללא הפרעות" +### Case 3: "I need 24/7 coding, no interruptions" -**בעיה:** מועדים, לא יכול להרשות לעצמו זמן השבתה +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### מקרה 4: "אני רוצה AI בחינם ב-OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**בעיה:** צריך עוזר בינה מלאכותית באפליקציות הודעות, בחינם לחלוטין +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 הגדרת ספק +## 📖 Provider Setup -### 🔐 ספקי מנויים +### 🔐 Subscription Providers -#### קלוד קוד (פרו/מקס) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**טיפ מקצוען:** השתמש ב-Opus למשימות מורכבות, בסונט למהירות. OmniRoute עוקב אחר מכסה לכל דגם! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### OpenAI Codex (פלוס/פרו) +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (180K בחינם לחודש!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,7 +152,7 @@ Models: gc/gemini-2.5-pro ``` -**הערך הטוב ביותר:** שכבת חינם ענקית! השתמש בזה לפני שכבות בתשלום. +**Best Value:** Huge free tier! Use this before paid tiers. #### GitHub Copilot @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 ספקים זולים +### 💰 Cheap Providers -#### GLM-4.7 (איפוס יומי, $0.6/1M) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. הירשם: [Zhipu AI](https://open.bigmodel.cn/) -2. קבל מפתח API מ-Coding Plan -3. לוח מחוונים ← הוסף מפתח API: ספק: `glm`, מפתח API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**שימוש:** `glm/glm-4.7` — **טיפ מקצועי:** תוכנית קידוד מציעה מכסה של 3× בעלות של 1/7! איפוס כל יום 10:00 בבוקר. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (איפוס של 5 שעות, $0.20/1 מיליון) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. הירשם: [MiniMax](https://www.minimax.io/) -2. קבל מפתח API → לוח מחוונים → הוסף מפתח API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**שימוש:** `minimax/MiniMax-M2.1` — **טיפ מקצועי:** האפשרות הזולה ביותר להקשר ארוך (מיליון אסימונים)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (דירה של 9$ לחודש) +#### Kimi K2 ($9/month flat) -1. הירשם: [Moonshot AI](https://platform.moonshot.ai/) -2. קבל מפתח API → לוח מחוונים → הוסף מפתח API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**שימוש:** `kimi/kimi-latest` — **טיפ מקצועי:** קבוע $9 לחודש עבור 10 מיליון אסימונים = $0.90/1 מיליון עלות אפקטיבית! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 ספקים בחינם +### 🆓 FREE Providers -#### iFlow (8 דגמים בחינם) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 דגמים בחינם) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### קירו (קלוד בחינם) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 שילובים +## 🎨 Combos -### דוגמה 1: הגדלת מנוי ← גיבוי זול +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### דוגמה 2: חינם בלבד (עלות אפס) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 שילוב CLI +## 🔧 CLI Integration -### סמן IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### קלוד קוד +### Claude Code -ערוך את `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -ערוך את `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,7 +303,7 @@ codex "your prompt" } ``` -**או השתמש ב-Dashboard:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config ### Cline / Continue / RooCode @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 פריסה +## 🚀 Deployment -### פריסת VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### דוקר +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -למצב משולב מארח עם קבצים בינאריים של CLI, עיין בסעיף Docker במסמכים הראשיים. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### משתני סביבה +### Environment Variables -| משתנה | ברירת מחדל | תיאור | -| --------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | סוד חתימת JWT (**שינוי בייצור**) | -| `INITIAL_PASSWORD` | `123456` | סיסמת כניסה ראשונה | -| `DATA_DIR` | `~/.omniroute` | ספריית נתונים (db, שימוש, יומנים) | -| `PORT` | ברירת המחדל של מסגרת | יציאת שירות (`20128` בדוגמאות) | -| `HOSTNAME` | ברירת המחדל של מסגרת | מארח איגד (Docker ברירת המחדל היא `0.0.0.0`) | -| `NODE_ENV` | ברירת המחדל של זמן ריצה | הגדר את `production` לפריסה | -| `BASE_URL` | `http://localhost:20128` | כתובת URL בסיס פנימית בצד השרת | -| `CLOUD_URL` | `https://omniroute.dev` | כתובת אתר בסיס של נקודת קצה לסנכרון בענן | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | סוד HMAC עבור מפתחות API שנוצרו | -| `REQUIRE_API_KEY` | `false` | לאכוף מפתח API של Bearer ב-`/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | מאפשר יומני בקשות/תגובות | -| `AUTH_COOKIE_SECURE` | `false` | כפה עוגיית אישור `Secure` (מאחורי פרוקסי הפוך של HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -להפניה מלאה למשתנה הסביבה, עיין ב-[README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 דגמים זמינים +## 📊 Available Models
-הצג את כל הדגמים הזמינים +View all available models -**קוד קלוד (`cc/`)** — פרו/מקסימום: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**קודקס (`cx/`)** — פלוס/יתרונות: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — בחינם: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — $0.6/1 מיליון: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $0.2/1 מיליון: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — בחינם: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — בחינם: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — בחינם: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -399,17 +458,17 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat **xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**מיסטרל (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**תמיהה (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` **Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -** Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**מוחין (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**קוהר (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat --- -## 🧩 תכונות מתקדמות +## 🧩 Advanced Features -### דגמים מותאמים אישית +### Custom Models -הוסף מזהה דגם לכל ספק מבלי לחכות לעדכון אפליקציה: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -או השתמש בלוח המחוונים: **ספקים ← [ספק] ← דגמים מותאמים אישית**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### מסלולי ספקים ייעודיים +### Dedicated Provider Routes -נתב בקשות ישירות לספק ספציפי עם אימות מודל: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -קידומת הספק מתווספת אוטומטית אם חסרה. דגמים לא תואמים מחזירים `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### תצורת Proxy Network +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**עדיפות:** ספציפית למפתח → ספציפי לשילוב → ספציפי לספק → גלובלי → סביבה. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### ממשק API של קטלוג דגמים +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -מחזירה דגמים מקובצים לפי ספק עם סוגים (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### סנכרון ענן +### Cloud Sync -- סנכרון ספקים, שילובים והגדרות בין מכשירים -- סנכרון רקע אוטומטי עם פסק זמן + כשל מהיר -- העדיפו את `BASE_URL`/`CLOUD_URL` בצד השרת בייצור +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (שלב 9) +### LLM Gateway Intelligence (Phase 9) -- **מטמון סמנטי** - מטמון אוטומטי ללא סטרימינג, טמפרטורה=0 תגובות (עקוף עם `X-OmniRoute-No-Cache: true`) -- **בקש אימפוטנציה** - ביטול כפילויות של בקשות תוך 5 שניות באמצעות כותרת `Idempotency-Key` או `X-Request-Id` -- **מעקב אחר התקדמות** — הצטרפות לאירועי SSE `event: progress` דרך כותרת `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### מגרש משחקים לתרגום +### Translator Playground -גישה דרך **לוח מחוונים ← מתרגם**. נפה באגים ודמיין כיצד OmniRoute מתרגם בקשות API בין ספקים. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| מצב | מטרה | -| --------------- | ---------------------------------------------------------------------- | -| **מגרש משחקים** | בחר פורמטים של מקור/יעד, הדבק בקשה וראה את הפלט המתורגם באופן מיידי | -| **בודק צ'אט** | שלח הודעות צ'אט חי דרך ה-proxy ובדוק את מחזור הבקשה/התגובה המלא | -| **ספסל מבחן** | הפעל בדיקות אצווה על פני מספר שילובי פורמטים כדי לאמת את נכונות התרגום | -| **שידור חי** | צפה בתרגומים בזמן אמת כאשר בקשות זורמות דרך ה-proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**מקרי שימוש:** +**Use cases:** -- איתור באגים מדוע שילוב לקוח/ספק ספציפי נכשל -- ודא שתגי חשיבה, קריאות לכלים והנחיות מערכת מתורגמות כהלכה -- השווה הבדלי פורמטים בין פורמטים של OpenAI, Claude, Gemini ו-Respons API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### אסטרטגיות ניתוב +### Routing Strategies -הגדר דרך **לוח מחוונים ← הגדרות ← ניתוב**. +Configure via **Dashboard → Settings → Routing**. -| אסטרטגיה | תיאור | -| ----------------------------- | -------------------------------------------------------------------------------- | -| **מילוי ראשון** | משתמש בחשבונות לפי סדר עדיפות - החשבון הראשי מטפל בכל הבקשות עד שהוא לא זמין | -| **עגול רובין** | עובר על כל החשבונות עם מגבלה דביקה הניתנת להגדרה (ברירת מחדל: 3 שיחות לחשבון) | -| **P2C (כוח של שתי אפשרויות)** | בוחר 2 חשבונות אקראיים ומסלולים לאחד הבריא יותר - מאזן עומס עם מודעות לבריאות | -| **אקראי** | בוחר באקראי חשבון עבור כל בקשה באמצעות Fisher-Yates Shuffle | -| **פחות בשימוש** | מסלולים לחשבון עם חותמת הזמן הוותיקה ביותר `lastUsedAt`, חלוקת התנועה באופן שווה | -| **אופטימיזציה לעלות** | מסלולים לחשבון עם ערך העדיפות הנמוך ביותר, אופטימיזציה לספקים בעלות הנמוכה ביותר | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### כינויים של מודל עם תווים כלליים לחיפוש +#### Wildcard Model Aliases -צור דפוסי תווים כלליים למיפוי מחדש של שמות מודלים: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -תווים כלליים תומכים ב-`*` (כל תווים) וב-`?` (תו בודד). +Wildcards support `*` (any characters) and `?` (single character). -#### שרשראות Fallback +#### Fallback Chains -הגדר שרשראות חילופין גלובליות החלות על כל הבקשות: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### חוסן ומפסקי חשמל +### Resilience & Circuit Breakers -הגדר דרך **לוח מחוונים ← הגדרות ← חוסן**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute מיישמת חוסן ברמת הספק עם ארבעה מרכיבים: +OmniRoute implements provider-level resilience with four components: -1. **פרופילי ספק** — תצורה לכל ספק עבור: - - סף כשל (כמה כשלים לפני הפתיחה) - - משך ההתקררות - - רגישות לזיהוי מגבלת שיעור - - פרמטרי גיבוי אקספוננציאליים +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **מגבלות שיעור הניתנות לעריכה** — ברירות מחדל ברמת המערכת הניתנות להגדרה בלוח המחוונים: - - **בקשות לדקה (RPM)** - מקסימום בקשות לדקה לחשבון - - **מינימום זמן בין בקשות** - פער מינימלי באלפיות שניות בין בקשות - - **מקסימום בקשות במקביל** - מקסימום בקשות בו-זמניות לכל חשבון - - לחץ על **ערוך** כדי לשנות, ולאחר מכן על **שמור** או **ביטול**. הערכים נמשכים באמצעות ממשק API לחוסן. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **מפסק מעגלים** - עוקב אחר כשלים לכל ספק ופותח את המעגל באופן אוטומטי כאשר מגיעים לסף: - - **סגור** (בריא) - הבקשות זורמות כרגיל - - **פתוח** - הספק נחסם זמנית לאחר כשלים חוזרים ונשנים - - **HALF_OPEN** - בדיקה אם הספק התאושש +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **מדיניות ומזהים נעולים** — מציג את מצב מפסק החשמל ומזהים נעולים עם יכולת פתיחה בכוח. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **זיהוי אוטומטי של מגבלת תעריף** — עקוב אחר כותרות `429` ו`Retry-After` כדי להימנע באופן יזום מפגיעה במגבלות התעריפים של הספקים. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**טיפ מקצוען:** השתמש בלחצן **אפס הכל** כדי לנקות את כל מפסקי החשמל וההתקררות כאשר ספק מתאושש מהפסקה. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### ייצוא/ייבוא של מסד נתונים +### Database Export / Import -נהל גיבויים של מסדי נתונים ב-**לוח מחוונים → הגדרות → מערכת ואחסון**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| פעולה | תיאור | -| ---------------------- | ------------------------------------------------------------------------------------------------------------ | -| **ייצוא מסד נתונים** | מוריד את מסד הנתונים הנוכחי של SQLite כקובץ `.sqlite` | -| **ייצא הכל (.tar.gz)** | מוריד ארכיון גיבוי מלא כולל: מסד נתונים, הגדרות, שילובים, חיבורי ספקים (ללא אישורים), מטא נתונים של מפתח API | -| **ייבוא ​​מסד נתונים** | העלה קובץ `.sqlite` כדי להחליף את מסד הנתונים הנוכחי. גיבוי טרום-ייבוא ​​נוצר אוטומטית | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**אימות יבוא:** הקובץ המיובא מאומת עבור תקינות (בדיקת פרגמה של SQLite), טבלאות נדרשות (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) וגודל (מקסימום 100MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**מקרי שימוש:** +**Use Cases:** -- העבר OmniRoute בין מכונות -- צור גיבויים חיצוניים להתאוששות מאסון -- שתף תצורות בין חברי הצוות (ייצא הכל → שתף ארכיון) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### לוח המחוונים של הגדרות +### Settings Dashboard -דף ההגדרות מאורגן ב-5 כרטיסיות לניווט קל: +The settings page is organized into 5 tabs for easy navigation: -| לשונית | תוכן | -| --------- | ---------------------------------------------------------------------------------------------------------- | -| **אבטחה** | הגדרות התחברות/סיסמה, בקרת גישה ל-IP, אישור API עבור `/models`, וחסימת ספק | -| **ניתוב** | אסטרטגיית ניתוב גלובלית (6 אפשרויות), כינויים של מודלים עם תווים כלליים, שרשרות חזרות, ברירות מחדל משולבות | -| **חוסן** | פרופילי ספקים, מגבלות תעריף הניתנות לעריכה, מצב מפסק זרם, מדיניות ומזהים נעולים | -| **AI** | חשיבה על תצורת תקציב, הזרקת הנחיות למערכת גלובלית, סטטיסטיקת מטמון פקודה | -| **מתקדם** | תצורת פרוקסי גלובלית (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### עלויות וניהול תקציב +### Costs & Budget Management -גישה דרך **לוח המחוונים ← עלויות**. +Access via **Dashboard → Costs**. -| לשונית | מטרה | -| --------- | ------------------------------------------------------------------------------- | -| **תקציב** | הגדר מגבלות הוצאה לכל מפתח API עם תקציבים יומיים/שבועיים/חודשיים ומעקב בזמן אמת | -| **תמחור** | הצג וערוך ערכי תמחור של מודל - עלות לכל 1K אסימוני קלט/פלט לכל ספק | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**מעקב עלויות:** כל בקשה מתעדת את השימוש באסימונים ומחשבת עלות באמצעות טבלת התמחור. הצג פירוטים ב-**לוח מחוונים → שימוש** לפי ספק, דגם ומפתח API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### תמלול אודיו +### Audio Transcription -OmniRoute תומך בתמלול אודיו דרך נקודת הקצה התואמת OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -ספקים זמינים: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -פורמטי שמע נתמכים: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### אסטרטגיות איזון משולבות +### Combo Balancing Strategies -הגדר איזון לכל שילוב ב-**לוח מחוונים ← שילובים ← יצירה/עריכה ← אסטרטגיה**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| אסטרטגיה | תיאור | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | + +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. + +--- + +### Health Dashboard + +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: + +| Card | What It Shows | | --------------------- | ----------------------------------------------------------- | -| **סיבוב רובין** | מסתובב בין דגמים ברצף | -| **עדיפות** | תמיד מנסה את הדגם הראשון; נופל רק על שגיאה | -| **אקראי** | בוחר דגם אקראי מהשילוב עבור כל בקשה | -| **משוקלל** | מסלולים באופן פרופורציונלי על בסיס משקלים מוקצים לדגם | -| **פחות בשימוש** | מסלול למודל עם הכי מעט בקשות אחרונות (משתמש במדדים משולבים) | -| **אופטימיזציית עלות** | מסלולים לדגם הזול ביותר הזמין (משתמש בטבלת תמחור) | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -ניתן להגדיר ברירות מחדל גלובליות משולבות ב-**לוח מחוונים → הגדרות → ניתוב → ברירות מחדל משולבות**. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. --- -### לוח מחוונים לבריאות +## 🖥️ Desktop Application (Electron) -גישה דרך **לוח מחוונים → בריאות**. סקירת תקינות מערכת בזמן אמת עם 6 כרטיסים: +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. -| כרטיס | מה זה מראה | -| ------------------- | ---------------------------------------------------------- | -| **סטטוס מערכת** | זמן פעולה, גרסה, שימוש בזיכרון, ספריית נתונים | -| **בריאות הספק** | מצב מפסק זרם לכל ספק (סגור/פתוח/חצי פתוח) | -| **מגבלות תעריפים** | צינון מגבלת תעריף פעיל לכל חשבון עם הזמן שנותר | -| **נעילות אקטיביות** | ספקים חסומים זמנית על ידי מדיניות הנעילה | -| **מטמון חתימה** | סטטיסטיקת מטמון מניעת כפילויות (מפתחות פעילים, קצב כניסות) | -| **טלמטריית אחזור** | צבירת זמן אחזור p50/p95/p99 לכל ספק | +### Installation -**טיפ מקצועי:** דף הבריאות מתרענן אוטומטית כל 10 שניות. השתמש בכרטיס המפסק כדי לזהות אילו ספקים נתקלים בבעיות. +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/hu/API_REFERENCE.md b/docs/i18n/hu/API_REFERENCE.md index 904be52a50..b795722c11 100644 --- a/docs/i18n/hu/API_REFERENCE.md +++ b/docs/i18n/hu/API_REFERENCE.md @@ -1,12 +1,12 @@ -# API-referencia +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Teljes referencia az összes OmniRoute API-végponthoz. +Complete reference for all OmniRoute API endpoints. --- -## Tartalomjegyzék +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Teljes referencia az összes OmniRoute API-végponthoz. --- -## Csevegés befejezése +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Egyéni fejlécek +### Custom Headers -| Fejléc | Irány | Leírás | -| ------------------------ | ------ | ---------------------------------------------------- | -| `X-OmniRoute-No-Cache` | Kérés | Állítsa `true` értékre a gyorsítótár megkerüléséhez | -| `X-OmniRoute-Progress` | Kérés | Állítsa `true` értékre az előrehaladási eseményekhez | -| `Idempotency-Key` | Kérés | Dedup kulcs (5s ablak) | -| `X-Request-Id` | Kérés | Alternatív dedup kulcs | -| `X-OmniRoute-Cache` | Válasz | `HIT` vagy `MISS` (nem adatfolyam) | -| `X-OmniRoute-Idempotent` | Válasz | `true`, ha deduplikált | -| `X-OmniRoute-Progress` | Válasz | `enabled` ha a haladás követése a | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Beágyazások +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Elérhető szolgáltatók: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Képgenerálás +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Elérhető szolgáltatók: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Modellek listázása +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Kompatibilitási végpontok +## Compatibility Endpoints -| Módszer | Útvonal | Formátum | -| ------- | --------------------------- | ------------------------ | -| POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Antropikus | -| POST | `/v1/responses` | OpenAI válaszok | -| POST | `/v1/embeddings` | OpenAI | -| POST | `/v1/images/generations` | OpenAI | -| GET | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Antropikus | -| GET | `/v1beta/models` | Ikrek | -| POST | `/v1beta/models/{...path}` | Gemini GenerationContent | -| POST | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Dedikált szolgáltatói útvonalak +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -A szolgáltató előtagja automatikusan hozzáadódik, ha hiányzik. A nem egyező modellek a következőt adják vissza: `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Szemantikus gyorsítótár +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Válasz példa: +Response example: ```json { @@ -162,154 +162,164 @@ Válasz példa: --- -## Irányítópult és kezelés +## Dashboard & Management -### Hitelesítés +### Authentication -| Végpont | Módszer | Leírás | -| ----------------------------- | ------- | ----------------------- | -| `/api/auth/login` | POST | Bejelentkezés | -| `/api/auth/logout` | POST | Kijelentkezés | -| `/api/settings/require-login` | GET/PUT | Bejelentkezés szükséges | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Szolgáltatói menedzsment +### Provider Management -| Végpont | Módszer | Leírás | -| ---------------------------- | --------------- | ------------------------------------------- | -| `/api/providers` | GET/POST | Szolgáltatók listázása/létrehozása | -| `/api/providers/[id]` | GET/PUT/DELETE | Szolgáltató kezelése | -| `/api/providers/[id]/test` | POST | Szolgáltatói kapcsolat tesztelése | -| `/api/providers/[id]/models` | GET | Szolgáltatói modellek listázása | -| `/api/providers/validate` | POST | A szolgáltató konfigurációjának ellenőrzése | -| `/api/provider-nodes*` | Különféle | Szolgáltatói csomópontok kezelése | -| `/api/provider-models` | GET/POST/DELETE | Egyedi modellek | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth-folyamatok +### OAuth Flows -| Végpont | Módszer | Leírás | -| -------------------------------- | --------- | ---------------------------- | -| `/api/oauth/[provider]/[action]` | Különféle | Szolgáltató-specifikus OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | ### Routing & Config -| Végpont | Módszer | Leírás | -| --------------------- | --------- | ----------------------------------------- | -| `/api/models/alias` | GET/POST | Modell álnevek | -| `/api/models/catalog` | GET | Minden modell szolgáltató + típus szerint | -| `/api/combos*` | Különféle | Kombinált menedzsment | -| `/api/keys*` | Különféle | API-kulcskezelés | -| `/api/pricing` | GET | Modell árképzés | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Használat és elemzések +### Usage & Analytics -| Végpont | Módszer | Leírás | -| --------------------------- | ------- | -------------------------- | -| `/api/usage/history` | GET | Használati előzmények | -| `/api/usage/logs` | GET | Használati naplók | -| `/api/usage/request-logs` | GET | Kérelem szintű naplók | -| `/api/usage/[connectionId]` | GET | Kapcsolatonkénti használat | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Beállítások +### Settings -| Végpont | Módszer | Leírás | -| ------------------------------- | ------- | ------------------------------------ | -| `/api/settings` | GET/PUT | Általános beállítások | -| `/api/settings/proxy` | GET/PUT | Hálózati proxy konfiguráció | -| `/api/settings/proxy/test` | POST | Proxy kapcsolat tesztelése | -| `/api/settings/ip-filter` | GET/PUT | IP engedélyezési lista/blokkolólista | -| `/api/settings/thinking-budget` | GET/PUT | Indoklási jelképes költségvetés | -| `/api/settings/system-prompt` | GET/PUT | Globális rendszerkérdés | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | ### Monitoring -| Végpont | Módszer | Leírás | -| ------------------------ | ---------- | -------------------------------- | -| `/api/sessions` | GET | Aktív munkamenet-követés | -| `/api/rate-limits` | GET | Számlánkénti kamatkorlátok | -| `/api/monitoring/health` | GET | állapotfelmérés | -| `/api/cache` | GET/DELETE | Gyorsítótár statisztika / törlés | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Biztonsági mentés és exportálás/importálás +### Backup & Export/Import -| Végpont | Módszer | Leírás | -| --------------------------- | ------- | ---------------------------------------------------------- | -| `/api/db-backups` | GET | Az elérhető biztonsági másolatok listája | -| `/api/db-backups` | PUT | Kézi biztonsági mentés létrehozása | -| `/api/db-backups` | POST | Visszaállítás egy adott biztonsági másolatból | -| `/api/db-backups/export` | GET | Adatbázis letöltése .sqlite fájlként | -| `/api/db-backups/import` | POST | Töltse fel az .sqlite fájlt az adatbázis | -| `/api/db-backups/exportAll` | GET | A teljes biztonsági másolat letöltése .tar.gz archívumként | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | ### Cloud Sync -| Végpont | Módszer | Leírás | -| ---------------------- | --------- | ------------------------------- | -| `/api/sync/cloud` | Különféle | Felhő szinkronizálási műveletek | -| `/api/sync/initialize` | POST | Szinkronizálás inicializálása | -| `/api/cloud/*` | Különféle | Felhőkezelés | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI eszközök +### CLI Tools -| Végpont | Módszer | Leírás | -| ---------------------------------- | ------- | ------------------------ | -| `/api/cli-tools/claude-settings` | GET | Claude CLI állapota | -| `/api/cli-tools/codex-settings` | GET | Codex CLI állapota | -| `/api/cli-tools/droid-settings` | GET | Droid CLI állapot | -| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI állapota | -| `/api/cli-tools/runtime/[toolId]` | GET | Általános CLI futásidejű | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -A CLI-válaszok a következők: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Rugalmassági és sebességi korlátok +### ACP Agents -| Végpont | Módszer | Leírás | -| ----------------------- | ------- | ------------------------------------------- | -| `/api/resilience` | GET/PUT | Rugalmassági profilok beszerzése/frissítése | -| `/api/resilience/reset` | POST | Megszakítók visszaállítása | -| `/api/rate-limits` | GET | számlánkénti kamatláb korlát állapota | -| `/api/rate-limit` | GET | Globális díjkorlát konfiguráció | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | ### Evals -| Végpont | Módszer | Leírás | -| ------------ | -------- | -------------------------------------------- | -| `/api/evals` | GET/POST | Eval suites listázás / kiértékelés futtatása | +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -### Irányelvek +### Policies -| Végpont | Módszer | Leírás | -| --------------- | --------------- | -------------------------------- | -| `/api/policies` | GET/POST/DELETE | Útválasztási házirendek kezelése | +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -### Megfelelés +### Compliance -| Végpont | Módszer | Leírás | -| --------------------------- | ------- | ------------------------------------------ | -| `/api/compliance/audit-log` | GET | Megfelelőségi ellenőrzési napló (utolsó N) | +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### v1beta (Gemini-kompatibilis) +### v1beta (Gemini-Compatible) -| Végpont | Módszer | Leírás | -| -------------------------- | ------- | ----------------------------------- | -| `/v1beta/models` | GET | Modellek listája Gemini formátumban | -| `/v1beta/models/{...path}` | POST | Gemini `generateContent` végpont | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -Ezek a végpontok tükrözik a Gemini API-formátumát azon ügyfelek számára, akik natív Gemini SDK-kompatibilitást várnak el. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. -### Belső / Rendszer API-k +### Internal / System APIs -| Végpont | Módszer | Leírás | -| --------------- | ------- | ----------------------------------------------------------------- | -| `/api/init` | GET | Alkalmazás inicializálási ellenőrzése (első futtatáskor használt) | -| `/api/tags` | GET | Ollama-kompatibilis modellcímkék (Ollama ügyfelek számára) | -| `/api/restart` | POST | A kiszolgáló kecses újraindításának elindítása | -| `/api/shutdown` | POST | A kiszolgáló kecses leállításának elindítása | +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | -> **Megjegyzés:** Ezeket a végpontokat a rendszer belsőleg vagy az Ollama kliens kompatibilitás érdekében használja. Általában nem hívják a végfelhasználók. +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Hang átírása +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Írja át a hangfájlokat a Deepgram vagy az AssemblyAI segítségével. +Transcribe audio files using Deepgram or AssemblyAI. -**Kérés:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Válasz:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Támogatott szolgáltatók:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Támogatott formátumok:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Ollama kompatibilitás +## Ollama Compatibility -Az Ollama API formátumát használó ügyfelek számára: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -A kéréseket a rendszer automatikusan lefordítja az Ollama és a belső formátumok között. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetria +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Válasz:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Költségvetés +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## A modell elérhetősége +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Kérelem feldolgozása +## Request Processing -1. Az ügyfél kérelmet küld a következő címre: `/v1/*` -2. Az útvonalkezelő hívások: `handleChat`, `handleEmbedding`, `handleAudioTranscription` vagy `handleImageGeneration` -3. A modell feloldva (közvetlen szolgáltató/modell vagy álnév/kombináció) -4. A helyi adatbázisból kiválasztott hitelesítő adatok fiók elérhetőségi szűréssel -5. Csevegés esetén: `handleChatCore` — formátumészlelés, fordítás, gyorsítótár ellenőrzés, idempotencia ellenőrzés -6. A szolgáltató végrehajtója upstream kérést küld -7. A válasz visszafordítva ügyfélformátumra (csevegés) vagy visszaküldve (beágyazások/képek/audio) -8. Használat/naplózás rögzítve -9. A hibákra a tartalék a kombinált szabályok szerint érvényes +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Teljes architektúra hivatkozás: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Hitelesítés +## Authentication -- Az irányítópult útvonalai (`/dashboard/*`) `auth_token` cookie-t használnak -- A bejelentkezés elmentett jelszókivonatot használ; vissza a `INITIAL_PASSWORD` -- `requireLogin` átkapcsolható a következőn keresztül: `/api/settings/require-login` -- A `/v1/*` útvonalak opcionálisan megkövetelik a Bearer API kulcsot, amikor `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/hu/ARCHITECTURE.md b/docs/i18n/hu/ARCHITECTURE.md index d6ce23aff5..258d62df53 100644 --- a/docs/i18n/hu/ARCHITECTURE.md +++ b/docs/i18n/hu/ARCHITECTURE.md @@ -1,71 +1,71 @@ # OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Utolsó frissítés: 2026-02-18_ +_Last updated: 2026-03-04_ -## Vezetői összefoglaló +## Executive Summary -Az OmniRoute egy helyi mesterséges intelligencia-útválasztó átjáró és irányítópult, amely a Next.js-re épül. -Egyetlen OpenAI-kompatibilis végpontot (`/v1/*`) biztosít, és a forgalmat több upstream szolgáltató között irányítja át fordítással, tartalékkal, tokenfrissítéssel és használati követéssel. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Alapvető képességek: +Core capabilities: -- OpenAI-kompatibilis API felület a CLI-hez/eszközökhöz (28 szolgáltató) -- Fordítás kérése/válaszolása a szolgáltatói formátumok között -- Model kombinált tartalék (több modell sorozat) -- Fiókszintű tartalék (szolgáltatónként több fiók) -- OAuth + API-kulcs szolgáltatói kapcsolatkezelés -- Beágyazás generálása a `/v1/embeddings` segítségével (6 szolgáltató, 9 modell) -- Képgenerálás a `/v1/images/generations` segítségével (4 szolgáltató, 9 modell) -- Gondoljon a címkeelemzésre (`...`) az érvelési modellekhez -- Válasz fertőtlenítés a szigorú OpenAI SDK-kompatibilitás érdekében -- Szerepek normalizálása (fejlesztő→rendszer, rendszer→felhasználó) a szolgáltatók közötti kompatibilitás érdekében -- Strukturált kimenet átalakítás (json_schema → Gemini responseSchema) -- Helyi kitartás a szolgáltatók, kulcsok, álnevek, kombinációk, beállítások, árképzés számára -- Használat/költségkövetés és kérések naplózása -- Opcionális felhőszinkronizálás több eszköz/állapot szinkronizáláshoz -- IP engedélyezési/blokkolási lista API hozzáférés-vezérléshez -- Átgondolt költségvetés-kezelés (áthaladó/automatikus/egyéni/adaptív) -- Globális rendszer azonnali befecskendezése -- Munkamenet követés és ujjlenyomat -- Fiókonként továbbfejlesztett díjkorlátozás szolgáltató-specifikus profilokkal -- Megszakító minta a szolgáltatói rugalmasság érdekében -- Mennydörgés elleni állományvédelem mutex zárral -- Aláírás alapú kérés deduplikációs gyorsítótár -- Domain réteg: modell elérhetősége, költségszabályok, tartalék házirend, kizárási szabályzat -- Tartomány állapotának fennmaradása (SQLite átírási gyorsítótár tartalékok, költségvetések, zárolások, megszakítók számára) -- Házirend motor a kérelmek központosított értékeléséhez (zárás → költségvetés → tartalék) -- Telemetria kérése p50/p95/p99 késleltetési összesítéssel -- Korrelációs azonosító (X-Request-Id) a végpontok közötti nyomkövetéshez -- Megfelelőségi naplózás API-kulcsonkénti leiratkozással -- Eval keretrendszer az LLM minőségbiztosításhoz -- Rugalmas UI műszerfal valós idejű megszakító állapottal -- Moduláris OAuth-szolgáltatók (12 egyedi modul a `src/lib/oauth/providers/` alatt) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Elsődleges futásidejű modell: +Primary runtime model: -- A `src/app/api/*` alatti Next.js alkalmazásútvonalai irányítópult API-kat és kompatibilitási API-kat is megvalósítanak -- A `src/sse/*` + `open-sse/*` megosztott SSE/routing magja kezeli a szolgáltató végrehajtását, fordítását, adatfolyamát, tartalékát és használatát +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Hatály és határok +## Scope and Boundaries -### Hatáskörben +### In Scope -- Helyi átjáró futásidejű -- Irányítópult-kezelő API-k -- Szolgáltató hitelesítése és token frissítése -- Fordítás és SSE streaming kérése -- Helyi állapot + használat tartóssága -- Opcionális felhőszinkronizálás +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### A hatályon kívül +### Out of Scope -- Felhőszolgáltatás megvalósítása a `NEXT_PUBLIC_CLOUD_URL` mögött -- Szolgáltató SLA/vezérlő síkja a helyi folyamaton kívül -- Maguk a külső CLI binárisok (Claude CLI, Codex CLI stb.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Magas szintű rendszerkontextus +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Alapvető futásidejű összetevők +## Core Runtime Components -## 1) API és útválasztási réteg (Next.js App Routes) +## 1) API and Routing Layer (Next.js App Routes) -Fő könyvtárak: +Main directories: -- `src/app/api/v1/*` és `src/app/api/v1beta/*` a kompatibilitási API-khoz -- `src/app/api/*` a felügyeleti/konfigurációs API-khoz -- Következő átírások a `next.config.mjs` leképezésben `/v1/*` ide: `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Fontos kompatibilitási útvonalak: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` - egyéni modelleket tartalmaz `custom: true` -- `src/app/api/v1/embeddings/route.ts` - beágyazás generálása (6 szolgáltató) -- `src/app/api/v1/images/generations/route.ts` — képgenerálás (4+ szolgáltató, beleértve az Antigravitációt/Nebiust) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` – dedikált szolgáltatónkénti csevegés -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` – dedikált szolgáltatónkénti beágyazások -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` – szolgáltatónként dedikált képek +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Kezelési tartományok: +Management domains: -- Hitelesítés/beállítások: `src/app/api/auth/*`, `src/app/api/settings/*` -- Szolgáltatók/kapcsolatok: `src/app/api/providers*` -- Szolgáltató csomópontjai: `src/app/api/provider-nodes*` -- Egyedi modellek: `src/app/api/provider-models` (GET/POST/DELETE) -- Modellkatalógus: `src/app/api/models/catalog` (GET) -- Proxy konfigurációja: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Kulcsok/álnevek/kombók/árazás: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Használat: `src/app/api/usage/*` -- Szinkronizálás/felhő: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI-eszközök segédei: `src/app/api/cli-tools/*` -- IP-szűrő: `src/app/api/settings/ip-filter` (GET/PUT) -- Átgondolt költségvetés: `src/app/api/settings/thinking-budget` (GET/PUT) -- Rendszerprompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Munkamenetek: `src/app/api/sessions` (GET) -- Díjkorlátok: `src/app/api/rate-limits` (GET) -- Rugalmasság: `src/app/api/resilience` (GET/PATCH) – szolgáltatói profilok, megszakító, sebességkorlát állapot -- Rugalmasság visszaállítása: `src/app/api/resilience/reset` (POST) - megszakítók visszaállítása + lehűlés -- Gyorsítótár statisztikái: `src/app/api/cache/stats` (GET/DELETE) -- A modell elérhetősége: `src/app/api/models/availability` (GET/POST) -- Telemetria: `src/app/api/telemetry/summary` (GET) -- Költségkeret: `src/app/api/usage/budget` (GET/POST) -- Tartalékláncok: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Megfelelőségi ellenőrzés: `src/app/api/compliance/audit-log` (GET) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) - Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Irányelvek: `src/app/api/policies` (GET/POST) +- Policies: `src/app/api/policies` (GET/POST) ## 2) SSE + Translation Core -Fő áramlási modulok: +Main flow modules: -- Bejegyzés: `src/sse/handlers/chat.ts` -- Alaphangszerelés: `open-sse/handlers/chatCore.ts` -- Szolgáltatói végrehajtási adapterek: `open-sse/executors/*` -- Formátumészlelés/szolgáltató konfigurációja: `open-sse/services/provider.ts` -- Modell elemzés/feloldás: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Fiók tartalék logikája: `open-sse/services/accountFallback.ts` -- Fordítási nyilvántartás: `open-sse/translator/index.ts` -- Adatfolyam átalakítások: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Használat kibontása/normalizálása: `open-sse/utils/usageTracking.ts` -- Think címkeelemző: `open-sse/utils/thinkTagParser.ts` -- Beágyazáskezelő: `open-sse/handlers/embeddings.ts` -- Beágyazási szolgáltató nyilvántartása: `open-sse/config/embeddingRegistry.ts` -- Képgeneráló kezelő: `open-sse/handlers/imageGeneration.ts` -- Képszolgáltató nyilvántartása: `open-sse/config/imageRegistry.ts` -- Válasz fertőtlenítés: `open-sse/handlers/responseSanitizer.ts` -- Szerepkör normalizálása: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Szolgáltatások (üzleti logika): +Services (business logic): -- Fiókválasztás/pontozás: `open-sse/services/accountSelector.ts` -- Kontextus-életciklus-kezelés: `open-sse/services/contextManager.ts` -- IP-szűrő betartatása: `open-sse/services/ipFilter.ts` -- Munkamenetkövetés: `open-sse/services/sessionManager.ts` -- Deduplikáció kérése: `open-sse/services/signatureCache.ts` -- Rendszerkérdés: `open-sse/services/systemPrompt.ts` -- Gondolkodó költségvetés-kezelés: `open-sse/services/thinkingBudget.ts` -- Helyettesítő karakteres modell-útválasztás: `open-sse/services/wildcardRouter.ts` -- Díjkorlát kezelése: `open-sse/services/rateLimitManager.ts` -- Megszakító: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Domain réteg modulok: +Domain layer modules: -- A modell elérhetősége: `src/lib/domain/modelAvailability.ts` -- Költségszabályok/költségkeretek: `src/lib/domain/costRules.ts` -- Tartalék irányelv: `src/lib/domain/fallbackPolicy.ts` -- Kombinált feloldó: `src/lib/domain/comboResolver.ts` -- Kizárási szabályzat: `src/lib/domain/lockoutPolicy.ts` -- Irányelvmotor: `src/domain/policyEngine.ts` — központi zárolás → költségvetés → tartalék értékelés -- Hibakód-katalógus: `src/lib/domain/errorCodes.ts` -- Kérelem azonosítója: `src/lib/domain/requestId.ts` -- Lekérési időtúllépés: `src/lib/domain/fetchTimeout.ts` -- Telemetria kérése: `src/lib/domain/requestTelemetry.ts` -- Megfelelőség/ellenőrzés: `src/lib/domain/compliance/index.ts` -- Eval futó: `src/lib/domain/evalRunner.ts` -- A tartomány állapotának fennmaradása: `src/lib/db/domainState.ts` — SQLite CRUD tartalék láncokhoz, költségvetésekhez, költségelőzményekhez, zárolási állapothoz, megszakítókhoz +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth-szolgáltató modulok (12 külön fájl a `src/lib/oauth/providers/` alatt): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Nyilvántartási index: `src/lib/oauth/providers/index.ts` -- Egyéni szolgáltatók: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, ,\_118_TOK `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Vékony burkolat: `src/lib/oauth/providers.ts` - újraexportálás az egyes modulokból +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Perzisztencia réteg +## 3) Persistence Layer -Elsődleges állapot DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- fájl: `${DATA_DIR}/db.json` (vagy `$XDG_CONFIG_HOME/omniroute/db.json`, ha be van állítva, különben `~/.omniroute/db.json`) -- entitások: providerConnections, providerNodes, modelAliases, kombók, apiKeys, beállítások, árképzés, **customModels**, **proxyConfig**, **ipFilter**, **thhinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -DB használat: +Usage persistence: -- `src/lib/usageDb.ts` -- fájlok: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- ugyanazt az alapkönyvtár-házirendet követi, mint a `localDb` (`DATA_DIR`, majd `XDG_CONFIG_HOME/omniroute`, ha be van állítva) -- fókuszált almodulokra bontva: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present Domain State DB (SQLite): -- `src/lib/db/domainState.ts` - CRUD műveletek a tartomány állapotához -- Táblázatok (létrehozva: `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, -- Átírási gyorsítótár minta: a memórián belüli térképek mérvadóak futás közben; a mutációk szinkronban íródnak az SQLite-ba; állapot visszaáll a DB-ből hidegindításkor +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Auth + biztonsági felületek +## 4) Auth + Security Surfaces -- Az irányítópult cookie hitelesítése: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- API-kulcs létrehozása/ellenőrzése: `src/shared/utils/apiKey.ts` -- A szolgáltató titkai `providerConnections` bejegyzésben is megmaradtak -- Kimenő proxy támogatása a következőn keresztül: `open-sse/utils/proxyFetch.ts` (env vars) és `open-sse/utils/networkProxy.ts` (szolgáltatónként konfigurálható vagy globális) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) ## 5) Cloud Sync -- Ütemező init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Időszakos feladat: `src/shared/services/cloudSyncScheduler.ts` -- Irányítási útvonal: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Kérelem életciklusa (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Kombinált + fiók tartalék folyamat +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -A tartalék döntéseket az `open-sse/services/accountFallback.ts` vezérli állapotkódok és hibaüzenet-heurisztika használatával. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth beépítési és tokenfrissítési életciklus +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Az élő forgalom alatti frissítés a `open-sse/handlers/chatCore.ts`-ban történik a `refreshCredentials()` végrehajtón keresztül. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Cloud Sync életciklusa (Engedélyezés / Szinkronizálás / Letiltása) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Az időszakos szinkronizálást a `CloudSyncScheduler` váltja ki, ha a felhő engedélyezve van. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Adatmodell és tárolási térkép +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Fizikai tároló fájlok: +Physical storage files: -- fő állapot: `${DATA_DIR}/db.json` (vagy `$XDG_CONFIG_HOME/omniroute/db.json`, ha be van állítva, különben `~/.omniroute/db.json`) -- használati statisztika: `${DATA_DIR}/usage.json` -- kérésnapló sorai: `${DATA_DIR}/log.txt` -- opcionális fordítói/hibakereső munkamenetek kérése: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Telepítési topológia +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Modulleképezés (döntéskritikus) +## Module Mapping (Decision-Critical) -### Útvonal- és API-modulok +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: kompatibilitási API-k -- `src/app/api/v1/providers/[provider]/*`: dedikált szolgáltatónkénti útvonalak (csevegés, beágyazás, képek) -- `src/app/api/providers*`: szolgáltató CRUD, érvényesítés, tesztelés -- `src/app/api/provider-nodes*`: egyéni kompatibilis csomópontkezelés -- `src/app/api/provider-models`: egyéni modellkezelés (CRUD) -- `src/app/api/models/catalog`: teljes modellkatalógus API (minden típus szolgáltató szerint csoportosítva) -- `src/app/api/oauth/*`: OAuth/eszközkód folyamatok -- `src/app/api/keys*`: helyi API kulcs életciklusa -- `src/app/api/models/alias`: alias kezelés -- `src/app/api/combos*`: tartalék kombinált kezelés -- `src/app/api/pricing`: az árképzés felülbírálása a költségszámításhoz -- `src/app/api/settings/proxy`: proxy konfiguráció (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: kimenő proxy csatlakozási teszt (POST) -- `src/app/api/usage/*`: használati és naplózási API-k -- `src/app/api/sync/*` + `src/app/api/cloud/*`: felhőszinkronizálás és felhő felé néző segítők -- `src/app/api/cli-tools/*`: helyi CLI konfigurációs írók/ellenőrzők -- `src/app/api/settings/ip-filter`: IP-engedélyezési lista/blokkolista (GET/PUT) -- `src/app/api/settings/thinking-budget`: gondolkodó token költségvetési konfiguráció (GET/PUT) -- `src/app/api/settings/system-prompt`: globális rendszerprompt (GET/PUT) -- `src/app/api/sessions`: aktív munkamenet-lista (GET) -- `src/app/api/rate-limits`: számlánkénti kamatkorlát állapota (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) ### Routing and Execution Core -- `src/sse/handlers/chat.ts`: kéréselemzés, kombinált kezelés, fiókválasztó hurok -- `open-sse/handlers/chatCore.ts`: fordítás, végrehajtó feladás, újrapróbálkozás/frissítés kezelése, adatfolyam beállítása -- `open-sse/executors/*`: szolgáltató-specifikus hálózati és formátumviselkedés +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Fordítási nyilvántartó és formátumkonvertálók +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: fordítói nyilvántartás és hangszerelés -- Fordítók kérése: `open-sse/translator/request/*` -- Válaszfordítók: `open-sse/translator/response/*` -- Formátum állandók: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Kitartás +### Persistence -- `src/lib/localDb.ts`: állandó konfiguráció/állapot -- `src/lib/usageDb.ts`: használati előzmények és gördülő kérésnaplók +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Szolgáltatói végrehajtói lefedettség (stratégiai minta) +## Provider Executor Coverage (Strategy Pattern) -Minden szolgáltató rendelkezik egy speciális végrehajtóval, amely kiterjeszti a `BaseExecutor`-t (a `open-sse/executors/base.ts`-ban), amely URL-építést, fejléc-építést, újrapróbálkozást exponenciális visszalépéssel, hitelesítő adatok frissítését és az `execute()` hangszerelési módszert biztosítja. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Végrehajtó | Szolgáltató(k) | Különleges kezelés | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dinamikus URL/fejléc konfiguráció szolgáltatónként | -| `AntigravityExecutor` | Google Antigravitáció | Egyéni projekt/munkamenet azonosítók, Újrapróbálkozás-elemzés után | -| `CodexExecutor` | OpenAI Codex | Rendszerutasításokat szúr be, érvelési erőfeszítést kényszerít | -| `CursorExecutor` | Kurzor IDE | ConnectRPC protokoll, Protobuf kódolás, kérés aláírása ellenőrző összeggel | -| `GithubExecutor` | GitHub másodpilóta | Másodpilóta token frissítése, VSCode-utánzó fejlécek | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream bináris formátum → SSE konverzió | -| `GeminiCLIExecutor` | Gemini CLI | Google OAuth-token frissítési ciklus | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Az összes többi szolgáltató (beleértve az egyéni kompatibilis csomópontokat is) használja a `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Szolgáltatói kompatibilitási mátrix +## Provider Compatibility Matrix -| Szolgáltató | Formátum | Auth | Stream | Nem adatfolyam | Token Refresh | Használati API | -| ------------------ | ---------------- | ------------------------- | ------------------ | -------------- | ------------- | ------------------------- | -| Claude | claude | API kulcs / OAuth | ✅ | ✅ | ✅ | ⚠️ Csak adminisztrátor | -| Ikrek | ikrek | API kulcs / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Antigravitáció | antigravitáció | OAuth | ✅ | ✅ | ✅ | ✅ Teljes kvóta API | -| OpenAI | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-responses | OAuth | ✅ kényszer | ❌ | ✅ | ✅ Díjkorlátok | -| GitHub másodpilóta | openai | OAuth + másodpilóta token | ✅ | ✅ | ✅ | ✅ Kvóta pillanatképek | -| Kurzor | kurzor | Egyéni ellenőrző összeg | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (Eseményfolyam) | ❌ | ✅ | ✅ Felhasználási korlátok | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Kérésre | -| iFlow | openai | OAuth (alap) | ✅ | ✅ | ✅ | ⚠️ Kérésre | -| OpenRouter | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | API kulcs | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| Zavartság | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| Együtt AI | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| Tűzijáték AI | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| Cerebrák | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| Cohere | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Formátum fordítási lefedettség +## Format Translation Coverage -Az észlelt forrásformátumok a következők: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -A célformátumok a következők: +Target formats include: -- OpenAI chat/válaszok +- OpenAI chat/Responses - Claude -- Gemini/Gemini-CLI/Antigravitációs boríték +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Kurzor +- Cursor -A fordítások az **OpenAI-t használják hub-formátumként** – minden konverzió köztesként az OpenAI-n megy keresztül: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -A fordítások kiválasztása dinamikusan történik a forrás hasznos adat alakja és a szolgáltató célformátuma alapján. +Translations are selected dynamically based on source payload shape and provider target format. -További feldolgozási rétegek a fordítási folyamatban: +Additional processing layers in the translation pipeline: -- **Választisztítás** – Megszünteti a nem szabványos mezőket az OpenAI-formátumú válaszoktól (mind az adatfolyam-, mind a nem streameléstől) a szigorú SDK-megfelelőség biztosítása érdekében -- **Szerepnormalizálás** — `developer` → `system` konvertálása nem OpenAI-célokhoz; egyesíti a `system` → `user` a rendszerszerepkört elutasító modellekhez (GLM, ERNIE) -- **Think címke kivonatolás** — `...` blokkot elemzi a tartalomból a `reasoning_content` mezőbe -- **Strukturált kimenet** - Az OpenAI `response_format.json_schema` konvertálása Gemini `responseMimeType` + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Támogatott API-végpontok +## Supported API Endpoints -| Végpont | Formátum | Kezelő | -| -------------------------------------------------- | ----------------------- | ---------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Üzenetek | Ugyanaz a kezelő (automatikusan észlelve) | -| `POST /v1/responses` | OpenAI válaszok | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI beágyazások | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Modell lista | API útvonal | -| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Modell lista | API útvonal | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedikált szolgáltatónként modellellenőrzéssel | -| `POST /v1/providers/{provider}/embeddings` | OpenAI beágyazások | Dedikált szolgáltatónként modellellenőrzéssel | -| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedikált szolgáltatónként modellellenőrzéssel | -| `POST /v1/messages/count_tokens` | Claude Token Count | API útvonal | -| `GET /v1/models` | OpenAI modellek listája | API útvonal (csevegés + beágyazás + kép + egyéni modellek) | -| `GET /api/models/catalog` | Katalógus | Minden modell szolgáltató + típus szerint csoportosítva | -| `POST /v1beta/models/*:streamGenerateContent` | Ikrek bennszülött | API útvonal | -| `GET/PUT/DELETE /api/settings/proxy` | Proxy konfiguráció | Hálózati proxy konfiguráció | -| `POST /api/settings/proxy/test` | Proxy kapcsolat | Proxy állapot/kapcsolati teszt végpontja | -| `GET/POST/DELETE /api/provider-models` | Egyedi modellek | Egyéni modellkezelés szolgáltatónként | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | ## Bypass Handler -A bypass kezelő (`open-sse/utils/bypassHandler.ts`) elfogja a Claude CLI ismert "kidobási" kéréseit – bemelegítő pingeket, címkivonatokat és tokenszámlálást –, és **hamis választ** ad vissza anélkül, hogy felhasználná a upstream szolgáltatói tokeneket. Ez csak akkor aktiválódik, ha az `User-Agent` tartalmazza a `claude-cli` értéket. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Kérjen Logger Pipeline-t +## Request Logger Pipeline -A kérésnaplózó (`open-sse/utils/requestLogger.ts`) egy 7 szakaszból álló hibakeresési naplózási folyamatot biztosít, amely alapértelmezés szerint le van tiltva, és a következőn keresztül engedélyezett: `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -A fájlok a `/logs//` címre íródnak minden egyes kérési munkamenethez. +Files are written to `/logs//` for each request session. -## Hibamódok és rugalmasság +## Failure Modes and Resilience -## 1) Számla/szolgáltató elérhetősége +## 1) Account/Provider Availability -- szolgáltatói fiók lehűtése tranziens/sebesség/hitelesítési hibák esetén -- tartalék fiók a sikertelen kérés előtt -- kombinált modell tartalék, ha az aktuális modell/szolgáltató elérési útja kimerült +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Token lejárata +## 2) Token Expiry -- Előzetes ellenőrzés és frissítés újrapróbálkozással a frissíthető szolgáltatóknál -- 401/403 újrapróbálkozás frissítési kísérlet után az alapútvonalon +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Stream-biztonság +## 3) Stream Safety -- leválasztást érzékelő streamvezérlő -- fordítási adatfolyam a folyam végének kiürítésével és `[DONE]` kezelésével -- a használati becslés tartaléka, ha hiányoznak a szolgáltató használati metaadatai +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) A felhőszinkronizálás leromlása +## 4) Cloud Sync Degradation -- szinkronizálási hibák jelennek meg, de a helyi futásidő folytatódik -- Az ütemező rendelkezik újrapróbálkozásra alkalmas logikával, de az időszakos végrehajtás jelenleg alapértelmezés szerint egykísérletű szinkronizálást hív meg +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Adatintegritás +## 5) Data Integrity -- DB alakzat migráció/javítás a hiányzó kulcsok miatt -- sérült JSON-visszaállítási biztosítékok a localDb és a usageDb számára +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Megfigyelhetőség és működési jelek +## Observability and Operational Signals -Futásidejű láthatósági források: +Runtime visibility sources: -- konzolnaplók innen: `src/sse/utils/logger.ts` -- kérésenkénti használati összesítések a `usage.json`-ban -- szöveges kérés állapot bejelentkezés `log.txt` -- opcionális mélykérési/fordítási naplók a `logs/` alatt, amikor `ENABLE_REQUEST_LOGS=true` -- irányítópult-használati végpontok (`/api/usage/*`) a felhasználói felület használatához +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Biztonságra érzékeny határok +## Security-Sensitive Boundaries -- A JWT titkos (`JWT_SECRET`) biztosítja az irányítópult-munkamenet cookie-ellenőrzését/aláírását -- A kezdeti tartalék jelszót (`INITIAL_PASSWORD`, alapértelmezett `123456`) felül kell bírálni valós telepítéseknél -- API kulcs HMAC titkos (`API_KEY_SECRET`) biztosítja a generált helyi API kulcs formátumát -- A szolgáltatói titkok (API-kulcsok/tokenek) megmaradnak a helyi adatbázisban, és fájlrendszer-szinten védeni kell őket -- A felhőszinkronizálási végpontok API kulcs hitelesítés + gépazonosító szemantikára támaszkodnak +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Környezet és futásidejű mátrix +## Environment and Runtime Matrix -A kód által aktívan használt környezeti változók: +Environment variables actively used by code: -- Alkalmazás/hitelesítés: `JWT_SECRET`, `INITIAL_PASSWORD` -- Tárhely: `DATA_DIR` -- Kompatibilis csomópont viselkedése: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Opcionális tárhely-alap-felülírás (Linux/macOS, ha `DATA_DIR` nincs beállítva): `XDG_CONFIG_HOME` -- Biztonsági kivonatolás: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Naplózás: `ENABLE_REQUEST_LOGS` -- Szinkronizálás/felhő URL-elés: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Kimenő proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` és kisbetűs változatai -- SOCKS5 funkciójelzők: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Platform/futásidejű segítők (nem alkalmazás-specifikus konfiguráció): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Ismert építészeti megjegyzések +## Known Architectural Notes -1. `usageDb` és `localDb` most ugyanazt az alapkönyvtár-házirendet (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) osztja meg örökölt fájlmigrációval. -2. Az `/api/v1/route.ts` statikus modelllistát ad vissza, és nem a `/v1/models` által használt fő modellforrás. -3. A kérésnaplózó teljes fejlécet/törzsöt ír, ha engedélyezve van; a naplókönyvtárat érzékenyként kezeli. -4. A felhő viselkedése a helyes `NEXT_PUBLIC_BASE_URL` és a felhő-végpont elérhetőségétől függ. -5. Az `open-sse/` könyvtár `@omniroute/open-sse` **npm munkaterület-csomagként** lett közzétéve. A forráskód a `@omniroute/open-sse/...`-on keresztül importálja (a Next.js `transpilePackages` által megoldva). A dokumentum elérési útjai továbbra is a `open-sse/` könyvtárnevet használják a következetesség érdekében. -6. Az irányítópulton lévő diagramok **Újragrafikonokat** (SVG-alapú) használnak az elérhető, interaktív analitikai vizualizációkhoz (modellhasználati sávdiagramok, szolgáltatói bontási táblázatok sikerarányokkal). -7. Az E2E-tesztek a **Playwright**-ot (`tests/e2e/`) használják, a `npm run test:e2e`-on keresztül futnak. Az egységtesztek a **Node.js tesztfutót** (`tests/unit/`) használják, a `npm run test:plan3`-on keresztül futnak. A `src/` alatti forráskód **TypeScript** (`.ts`/`.tsx`); az `open-sse/` munkaterület továbbra is JavaScript marad (`.js`). -8. A Beállítások oldal 5 lapra van felosztva: Biztonság, Útválasztás (6 globális stratégia: kitöltés-első, kör-robin, p2c, véletlenszerű, legkevésbé használt, költségoptimalizált), Rugalmasság (szerkeszthető sebességkorlátok, megszakító, házirendek), AI (gondolkodó költségvetés, rendszerkérdés, gyorsítótár), Speciális (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Működési ellenőrzési ellenőrzőlista +## Operational Verification Checklist -- Forrás: `npm run build` -- Build Docker kép: `docker build -t omniroute .` -- Indítsa el a szervizt és ellenőrizze: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- A CLI cél alap URL-jének `http://:20128/v1` kell lennie, amikor `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/hu/CODEBASE_DOCUMENTATION.md b/docs/i18n/hu/CODEBASE_DOCUMENTATION.md index b00d88272c..303880c198 100644 --- a/docs/i18n/hu/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/hu/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Kódbázis-dokumentáció +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Átfogó, kezdőbarát útmutató az **omniroute** több szolgáltató AI-proxy routeréhez. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Mi az omniroute? +## 1. What Is omniroute? -Az omniroute egy **proxy router**, amely AI kliensek (Claude CLI, Codex, Cursor IDE stb.) és mesterséges intelligenciaszolgáltatók (Anthropic, Google, OpenAI, AWS, GitHub stb.) között helyezkedik el. Egy nagy problémát old meg: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **A különböző AI-kliensek különböző „nyelveket” (API-formátumokat) beszélnek, és a különböző AI-szolgáltatók is eltérő „nyelveket” várnak el.** Az omniroute automatikusan lefordítja őket. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Tekints úgy, mint egy univerzális fordító az Egyesült Nemzetek Szervezetében – minden küldött bármilyen nyelven beszélhet, és a fordító bármely más küldött számára átalakítja. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Építészet áttekintése +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Alapelv: Hub-and-spoke fordítás +### Core Principle: Hub-and-Spoke Translation -Minden formátumfordítás átmegy az **OpenAI formátumon, mint központon**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Ez azt jelenti, hogy csak **N fordítóra** (formátumonként egy) van szüksége a **N²** (minden pár) helyett. +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Projekt felépítése +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Modulonkénti lebontás +## 4. Module-by-Module Breakdown -### 4.1 konfiguráció (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -Az **egyetlen igazságforrás** minden szolgáltatói konfigurációhoz. +The **single source of truth** for all provider configuration. -| Fájl | Cél | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `constants.ts` | `PROVIDERS` objektum alap URL-ekkel, OAuth hitelesítési adatokkal (alapértelmezett), fejlécekkel és alapértelmezett rendszerkérdésekkel minden szolgáltatóhoz. Meghatározza a következőt is: `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` és `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Betölti a külső hitelesítő adatokat a `data/provider-credentials.json` helyről, és egyesíti őket a `PROVIDERS` merevkódolt alapértékeihez. Kizárja a titkokat a forrás ellenőrzése alól, miközben fenntartja a visszafelé kompatibilitást. | -| `providerModels.ts` | Központi modellnyilvántartás: térképszolgáltatói álnevek → modellazonosítók. Funkciók, mint például `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | A Codex kérésekbe beszúrt rendszerutasítások (szerkesztési megszorítások, sandbox-szabályok, jóváhagyási szabályzatok). | -| `defaultThinkingSignature.ts` | Claude és Gemini modellek alapértelmezett "gondolkodó" aláírásai. | -| `ollamaModels.ts` | Sémadefiníció helyi Ollama modellekhez (név, méret, család, kvantálás). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Hitelesítési adatok betöltésének folyamata +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Végrehajtók (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -A végrehajtók a **szolgáltató-specifikus logikát** a **stratégiai minta** segítségével foglalják magukba. Minden végrehajtó szükség szerint felülírja az alapmetódusokat. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Végrehajtó | Szolgáltató | Legfontosabb szakterületek | -| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Absztrakt alap: URL-építés, fejlécek, újrapróbálkozási logika, hitelesítő adatok frissítése | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Általános OAuth-token frissítés szabványos szolgáltatók számára | -| `antigravity.ts` | Google Cloud Code | Projekt/munkamenet azonosító generálása, több URL-es tartalék, egyéni újrapróbálkozás a hibaüzenetekből ("visszaállítás 2 óra 7 perc után") | -| `cursor.ts` | Kurzor IDE | **Legösszetettebb**: SHA-256 ellenőrzőösszeg hitelesítés, Protobuf kéréskódolás, bináris EventStream → SSE válaszelemzés | -| `codex.ts` | OpenAI Codex | Rendszerutasításokat injektál, gondolkodási szinteket kezel, eltávolítja a nem támogatott paramétereket | -| `gemini-cli.ts` | Google Gemini CLI | Egyéni URL-építés (`streamGenerateContent`), Google OAuth-token frissítése | -| `github.ts` | GitHub másodpilóta | Kettős token rendszer (GitHub OAuth + másodpilóta token), VSCode fejléc utánzás | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream bináris elemzés, AMZN eseménykeretek, token becslés | -| `index.ts` | — | Gyári: térképszolgáltató neve → végrehajtó osztály, alapértelmezett tartalék | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Kezelők (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -A **hangszerelési réteg** — koordinálja a fordítást, a végrehajtást, a streamelést és a hibakezelést. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Fájl | Cél | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Központi hangszerelő** (~600 sor). Kezeli a teljes kérés életciklust: formátumészlelés → fordítás → végrehajtó feladása → streaming/nem streaming válasz → token frissítés → hibakezelés → használati naplózás. | -| `responsesHandler.ts` | Adapter az OpenAI Responses API-jához: átalakítja a válaszformátumot → Chat Completions → elküldi a `chatCore` címre → konvertálja vissza az SSE-t válaszformátumba. | -| `embeddings.ts` | Beágyazás generációs kezelő: feloldja a beágyazási modellt → szolgáltató, elküldi a szolgáltató API-nak, visszaküldi az OpenAI-kompatibilis beágyazási választ. 6+ szolgáltatót támogat. | -| `imageGeneration.ts` | Képgeneráló kezelő: feloldja a képmodell → szolgáltatót, támogatja az OpenAI-kompatibilis, a Gemini-image (Antigravitáció) és a tartalék (Nebius) módokat. A base64 vagy URL képeket adja vissza. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Életciklus kérése (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Szolgáltatások (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Üzleti logika, amely támogatja a kezelőket és a végrehajtókat. +Business logic that supports the handlers and executors. -| Fájl | Cél | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Formátumészlelés** (`detectFormat`): elemzi a kérés törzsszerkezetét a Claude/OpenAI/Gemini/Antigravity/Responses formátumok azonosításához (beleértve a `max_tokens` heurisztikus Claude-ot). Továbbá: URL-építés, fejlécépítés, gondolkodási konfiguráció normalizálása. Támogatja a `openai-compatible-*` és `anthropic-compatible-*` dinamikus szolgáltatókat. | -| `model.ts` | Modellkarakterlánc-elemzés (`claude/model-name` → `{provider: "claude", model: "model-name"}`), álnév-feloldás ütközésészleléssel, bemeneti fertőtlenítés (elutasítja az útvonal bejárását/vezérlő karaktereket) és a modellinformáció-feloldás aszinkron alias getter támogatással. | -| `accountFallback.ts` | Rate-limit-kezelés: exponenciális visszalépés (1s → 2mp → 4mp → max 2perc), fiókhűtés-kezelés, hibabesorolás (mely hibák váltanak ki visszaesést, illetve nem). | -| `tokenRefresh.ts` | OAuth-token frissítése **minden szolgáltatóhoz**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + másodpilóta kettős token), Kiro (AWS SSO OIDC + Social Auth). Tartalmazza a menet közbeni ígéret-deduplikációs gyorsítótárat és az újrapróbálkozást exponenciális visszalépéssel. | -| `combo.ts` | **Kombinált modellek**: tartalék modellek láncai. Ha az A modell meghibásodik egy tartalék jogosultsági hibával, próbálja ki a B, majd a C modellt stb. A tényleges upstream állapotkódokat adja vissza. | -| `usage.ts` | Lekéri a kvóta/használati adatokat a szolgáltatói API-któl (GitHub másodpilóta kvóták, antigravitációs modellkvóták, Codex sebességkorlátok, Kiro használati lebontások, Claude beállítások). | -| `accountSelector.ts` | Intelligens számlakiválasztás pontozási algoritmussal: figyelembe veszi a prioritást, az egészségi állapotot, a körmérkőzéses pozíciót és a lemondási állapotot, hogy kiválaszthassa az optimális fiókot minden egyes kérelemhez. | -| `contextManager.ts` | Kéréskörnyezet-életciklus-kezelés: kérésenkénti kontextusobjektumokat hoz létre és nyomon követ metaadatokkal (kérelemazonosító, időbélyegek, szolgáltatói információk) hibakereséshez és naplózáshoz. | -| `ipFilter.ts` | IP-alapú hozzáférés-vezérlés: támogatja az engedélyezési listát és a tiltólistát. Az API-kérelmek feldolgozása előtt ellenőrzi az ügyfél IP-címét a konfigurált szabályok szerint. | -| `sessionManager.ts` | Munkamenetkövetés ügyfél ujjlenyomattal: nyomon követi az aktív munkameneteket kivonatolt ügyfélazonosítók segítségével, figyeli a kérések számát, és munkamenet-metrikákat biztosít. | -| `signatureCache.ts` | Aláírás-alapú deduplikációs gyorsítótár kérése: megakadályozza a duplikált kéréseket azáltal, hogy gyorsítótárazza a legutóbbi kérelmek aláírásait, és egy időablakon belül visszaadja a gyorsítótárazott válaszokat az azonos kérésekre. | -| `systemPrompt.ts` | Globális rendszerprompt injekció: minden kérés elé vagy hozzáfűz egy konfigurálható rendszerpromptot, szolgáltatónkénti kompatibilitáskezeléssel. | -| `thinkingBudget.ts` | Érvelési jogkivonat-költségvetés-kezelés: támogatja az áthárítást, az automatikus (szalagos gondolkodási konfiguráció), az egyéni (fix költségvetésű) és az adaptív (bonyolultságra skálázott) módokat a gondolkodási/érvelési tokenek vezérléséhez. | -| `wildcardRouter.ts` | Helyettesítő karakterminta-útválasztás: a helyettesítő karaktermintákat (pl. `*/claude-*`) konkrét szolgáltató/modell párokra oldja fel a rendelkezésre állás és a prioritás alapján. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Token frissítési deduplikáció +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Fiók tartalék állapotú gép +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Kombinált modelllánc +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Fordító (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -A **formátumfordító motor** egy önregisztráló bővítményrendszerrel. +The **format translation engine** using a self-registering plugin system. -#### Építészet +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Címtár | Fájlok | Leírás | -| ------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 fordító | A kéréstörzsek átalakítása formátumok között. Az importáláskor minden fájl önmagát regisztrálja a `register(from, to, fn)` segítségével. | -| `response/` | 7 fordító | A streaming válaszdarabok konvertálása formátumok között. Kezeli az SSE eseménytípusokat, gondolkodási blokkokat, eszközhívásokat. | -| `helpers/` | 6 segítő | Megosztott segédprogramok: `claudeHelper` (rendszerkérdések kibontása, gondolkodási konfiguráció), `geminiHelper` (alkatrészek/tartalom-leképezés), `openaiHelper` (formátumszűrés), `toolCallHelper`), _TOK_K_, hiányzó válasz_OM_8 `responsesApiHelper`. | -| `index.ts` | — | Fordítómotor: `translateRequest()`, `translateResponse()`, állapotkezelés, nyilvántartás. | -| `formats.ts` | — | Formátumkonstansok: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`_, _.EN*92_NI, *. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Kulcstervezés: Önregisztráló beépülő modulok +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -397,15 +397,15 @@ import "./request/claude-to-openai.js"; // ← self-registers ### 4.6 Utils (`open-sse/utils/`) -| Fájl | Cél | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Hibaválasz kiépítése (OpenAI-kompatibilis formátum), felfelé irányuló hibaelemzés, Antigravitációs újrapróbálkozási idő kivonat a hibaüzenetekből, SSE hibaadatfolyam. | -| `stream.ts` | **SSE Transform Stream** – a mag adatfolyam-folyamat. Két mód: `TRANSLATE` (teljes formátumú fordítás) és `PASSTHROUGH` (használat normalizálása + kibontása). Kezeli a darabok pufferelését, a felhasználás becslését, a tartalom hosszának követését. A folyamonkénti kódoló/dekódoló példányok elkerülik a megosztott állapotot. | -| `streamHelpers.ts` | Alacsony szintű SSE-segédprogramok: `parseSSELine` (szóköz-toleráns), `hasValuableContent` (üres darabokat szűr az OpenAI/Claude/Gemini számára), `fixInvalidId`, `perf_metrics` tisztítás). | -| `usageTracking.ts` | Tokenhasználati kinyerés bármilyen formátumból (Claude/OpenAI/Gemini/Responses), becslés külön eszköz/üzenet char-per-token arányokkal, puffer hozzáadása (2000 token biztonsági ráhagyás), formátum-specifikus mezőszűrés, konzolnaplózás ANSI színekkel. | -| `requestLogger.ts` | Fájlalapú kérések naplózása (feliratkozás a `ENABLE_REQUEST_LOGS=true` segítségével). Munkamenet mappákat hoz létre számozott fájlokkal: `1_req_client.json` → `7_res_client.txt`. Minden I/O aszinkron (gyújt és felejt). Elfedi az érzékeny fejléceket. | -| `bypassHandler.ts` | Elfogja a Claude CLI meghatározott mintáit (címkivonás, bemelegítés, számlálás), és hamis válaszokat ad vissza anélkül, hogy bármelyik szolgáltatót is felhívná. Támogatja a streaminget és a nem adatfolyamot egyaránt. Szándékosan a Claude CLI hatókörére korlátozva. | -| `networkProxy.ts` | Feloldja egy adott szolgáltató kimenő proxy URL-jét elsőbbséggel: szolgáltató-specifikus konfiguráció → globális konfiguráció → környezeti változók (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Támogatja a `NO_PROXY` kizárásokat. Gyorsítótár konfiguráció 30 másodpercig. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | #### SSE Streaming Pipeline @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Kérjen naplózó munkamenet-struktúrát +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Alkalmazási réteg (`src/`) +### 4.7 Application Layer (`src/`) -| Címtár | Cél | -| ------------- | -------------------------------------------------------------------------------------------- | -| `src/app/` | Webes felhasználói felület, API-útvonalak, Express köztes szoftver, OAuth visszahíváskezelők | -| `src/lib/` | Adatbázis-hozzáférés (`localDb.ts`, `usageDb.ts`), hitelesítés, megosztott | -| `src/mitm/` | Man-in-the-middle proxy segédprogramok a szolgáltatói forgalom lehallgatásához | -| `src/models/` | Adatbázismodell-definíciók | -| `src/shared/` | Az open-sse függvények körüli burkolók (szolgáltató, adatfolyam, hiba stb.) | -| `src/sse/` | SSE végpontkezelők, amelyek az open-sse könyvtárat az Express útvonalakhoz kötik | -| `src/store/` | Alkalmazás állapotkezelés | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Figyelemre méltó API-útvonalak +#### Notable API Routes -| Útvonal | Módszerek | Cél | -| --------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | GET/POST/DELETE | CRUD egyedi modellekhez szolgáltatónként | -| `/api/models/catalog` | GET | Összesített katalógus az összes modellről (csevegés, beágyazás, kép, egyéni) szolgáltató szerint csoportosítva | -| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchikus kimenő proxykonfiguráció (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Ellenőrzi a proxy-kapcsolatot, és visszaadja a nyilvános IP-címet/latenciát | -| `/v1/providers/[provider]/chat/completions` | POST | Dedikált szolgáltatónkénti csevegés-befejezések modellellenőrzéssel | -| `/v1/providers/[provider]/embeddings` | POST | Dedikált szolgáltatónkénti beágyazások modellellenőrzéssel | -| `/v1/providers/[provider]/images/generations` | POST | Dedikált szolgáltatónkénti képgenerálás modellellenőrzéssel | -| `/api/settings/ip-filter` | GET/PUT | IP engedélyezési lista/blokklista kezelése | -| `/api/settings/thinking-budget` | GET/PUT | Indoklási token költségkeret-konfiguráció (passthrough/auto/custom/adaptative) | -| `/api/settings/system-prompt` | GET/PUT | Globális rendszer azonnali befecskendezése minden kérelemhez | -| `/api/sessions` | GET | Aktív munkamenet-követés és mérőszámok | -| `/api/rate-limits` | GET | számlánkénti kamatláb korlát állapota | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Kulcsfontosságú tervezési minták +## 5. Key Design Patterns -### 5.1 Hub-and-Spoke fordítás +### 5.1 Hub-and-Spoke Translation -Minden formátum az **OpenAI formátumon keresztül történik, mint a hub**. Új szolgáltató hozzáadásához csak **egy pár** fordítót kell írni (OpenAI-ra/OpenAI-ról), N párra nem. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Végrehajtó stratégia minta +### 5.2 Executor Strategy Pattern -Minden szolgáltatónak van egy dedikált végrehajtó osztálya, amely a `BaseExecutor`-ból öröklődik. A `executors/index.ts` gyára futás közben választja ki a megfelelőt. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Önregisztráló beépülő modulrendszer +### 5.3 Self-Registering Plugin System -A fordítómodulok regisztrálják magukat az importáláskor a `register()` címen. Új fordító hozzáadása csak egy fájl létrehozását és importálását jelenti. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Fiók visszaállítása exponenciális visszalépéssel +### 5.4 Account Fallback with Exponential Backoff -Amikor egy szolgáltató visszaadja a 429/401/500 számot, a rendszer átválthat a következő fiókra, exponenciális lehűtést alkalmazva (1 mp → 2 mp → 4 mp → max 2 perc). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 kombinált modellláncok +### 5.5 Combo Model Chains -A „kombó” több `provider/model` karakterláncot csoportosít. Ha az első sikertelen, akkor automatikusan visszaáll a következőre. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Állapotalapú adatfolyam-fordítás +### 5.6 Stateful Streaming Translation -A válaszfordítás a `initState()` mechanizmuson keresztül fenntartja az állapotot az SSE-darabokon (gondolkodási blokk követése, eszközhívás-gyűjtés, tartalomblokk indexelése). +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Használati biztonsági puffer +### 5.7 Usage Safety Buffer -Egy 2000 tokenből álló puffert adunk a jelentett használathoz, hogy megakadályozzuk, hogy az ügyfelek elérjék a kontextusablak korlátait a rendszerkérések és a formátumfordítás miatti többletterhelés miatt. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Támogatott formátumok +## 6. Supported Formats -| Formátum | Irány | Azonosító | -| ----------------------- | ------------ | ------------------ | -| OpenAI Chat befejezések | forrás + cél | `openai` | -| OpenAI Responses API | forrás + cél | `openai-responses` | -| Antropikus Claude | forrás + cél | `claude` | -| Google Gemini | forrás + cél | `gemini` | -| Google Gemini CLI | csak cél | `gemini-cli` | -| Antigravitáció | forrás + cél | `antigravity` | -| AWS Kiro | csak cél | `kiro` | -| Kurzor | csak cél | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Támogatott szolgáltatók +## 7. Supported Providers -| Szolgáltató | Hitelesítési módszer | Végrehajtó | Főbb megjegyzések | -| ------------------------ | --------------------------- | --------------- | ---------------------------------------------------- | -| Antropikus Claude | API-kulcs vagy OAuth | Alapértelmezett | `x-api-key` fejlécet használ | -| Google Gemini | API-kulcs vagy OAuth | Alapértelmezett | `x-goog-api-key` fejlécet használ | -| Google Gemini CLI | OAuth | GeminiCLI | `streamGenerateContent` végpontot használ | -| Antigravitáció | OAuth | Antigravitáció | Több URL-es tartalék, egyéni újrapróbálkozás | -| OpenAI | API kulcs | Alapértelmezett | Normál hordozó hitelesítés | -| Codex | OAuth | Codex | Rendszerutasításokat ad be, irányítja a gondolkodást | -| GitHub másodpilóta | OAuth + másodpilóta token | Github | Kettős token, VSCode fejléc utánzás | -| Kiro (AWS) | AWS SSO OIDC vagy Social | Kiro | Bináris EventStream elemzés | -| Kurzor IDE | Ellenőrzőösszeg hitelesítés | Kurzor | Protobuf kódolás, SHA-256 ellenőrző összegek | -| Qwen | OAuth | Alapértelmezett | Normál hitelesítés | -| iFlow | OAuth (alap + hordozó) | Alapértelmezett | Kettős hitelesítési fejléc | -| OpenRouter | API kulcs | Alapértelmezett | Normál hordozó hitelesítés | -| GLM, Kimi, MiniMax | API kulcs | Alapértelmezett | Claude-kompatibilis, használja a `x-api-key` | -| `openai-compatible-*` | API kulcs | Alapértelmezett | Dinamikus: bármely OpenAI-kompatibilis végpont | -| `anthropic-compatible-*` | API kulcs | Alapértelmezett | Dinamikus: bármely Claude-kompatibilis végpont | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Adatfolyam összefoglalása +## 8. Data Flow Summary -### Streaming kérés +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Nem streamelési kérelem +### Non-Streaming Request ```mermaid flowchart LR diff --git a/docs/i18n/hu/FEATURES.md b/docs/i18n/hu/FEATURES.md index f3defd1d03..82cc73b67b 100644 --- a/docs/i18n/hu/FEATURES.md +++ b/docs/i18n/hu/FEATURES.md @@ -1,22 +1,22 @@ -# OmniRoute — Irányítópult-funkciók galériája +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Vizuális útmutató az OmniRoute irányítópult minden részéhez. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Szolgáltatók +## 🔌 Providers -AI-szolgáltatói kapcsolatok kezelése: OAuth-szolgáltatók (Claude Code, Codex, Gemini CLI), API-kulcs-szolgáltatók (Groq, DeepSeek, OpenRouter) és ingyenes szolgáltatók (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 kombók +## 🎨 Combos -Hozzon létre modell-útválasztási kombókat 6 stratégiával: kitöltés először, körbefutó, kettős választási lehetőség, véletlenszerű, legkevésbé használt és költségoptimalizált. Mindegyik kombó több modellt láncol automatikus visszaállítással. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) @@ -24,54 +24,119 @@ Hozzon létre modell-útválasztási kombókat 6 stratégiával: kitöltés elő ## 📊 Analytics -Átfogó használati elemzés token-fogyasztással, költségbecslésekkel, tevékenységi hőtérképekkel, heti elosztási diagramokkal és szolgáltatónkénti lebontásokkal. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Rendszer egészsége +## 🏥 System Health -Valós idejű megfigyelés: üzemidő, memória, verzió, késleltetési százalékok (p50/p95/p99), gyorsítótár-statisztika és szolgáltatói megszakító állapotok. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Fordítói Játszótér +## 🔧 Translator Playground -Négy mód az API-fordítások hibakeresésére: **Playground** (formátum-átalakító), **Chat Tester** (élő kérések), **Test Bench** (kötegelt tesztek) és **Élő figyelő** (valós idejű adatfolyam). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Beállítások +## 🎮 Model Playground _(v2.0.9+)_ -Általános beállítások, rendszertárolás, biztonsági mentések kezelése (export/import adatbázis), megjelenés (sötét/világos mód), biztonság (beleértve az API végpontvédelmet és az egyéni szolgáltatók blokkolását), útválasztás, rugalmasság és speciális konfiguráció. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI eszközök +## 🔧 CLI Tools -Egykattintásos konfiguráció az AI kódoló eszközökhöz: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code és Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Kérelemnaplók +## 🤖 CLI Agents _(v2.0.11+)_ -Valós idejű kérések naplózása szolgáltató, modell, fiók és API kulcs szerinti szűréssel. Megjeleníti az állapotkódokat, a tokenhasználatot, a várakozási időt és a válasz részleteit. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API végpont +## 🌐 API Endpoint -Az Ön egységes API-végpontja a képességek lebontásával: csevegési befejezések, beágyazások, képgenerálás, újrarangsorolás, hangátírás és regisztrált API-kulcsok. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/hu/TROUBLESHOOTING.md b/docs/i18n/hu/TROUBLESHOOTING.md index 7600d14f71..120092d63c 100644 --- a/docs/i18n/hu/TROUBLESHOOTING.md +++ b/docs/i18n/hu/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Hibaelhárítás +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Az OmniRoute gyakori problémái és megoldásai. +Common problems and solutions for OmniRoute. --- -## Gyors javítások +## Quick Fixes -| Probléma | Megoldás | -| ----------------------------------- | ----------------------------------------------------------------------------- | ---------- | -| Az első bejelentkezés nem működik | `INITIAL_PASSWORD` ellenőrzése itt: `.env` (alapértelmezett: `123456`) | -| A műszerfal rossz porton nyílik meg | `PORT=20128` és `NEXT_PUBLIC_BASE_URL=http://localhost:20128` beállítása | -| Nincsenek kérésnaplók a `logs/` | alatt `ENABLE_REQUEST_LOGS=true` | beállítása | -| EACCES: engedély megtagadva | `DATA_DIR=/path/to/writable/dir` beállítása a `~/.omniroute` felülbírálásához | -| Az útválasztási stratégia nem menti | Frissítés v1.4.11+ verzióra (Zod-séma javítása a beállítások fennmaradásához) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Szolgáltatói problémák +## Provider Issues -### "A nyelvi modell nem adott üzenetet" +### "Language model did not provide messages" -**Ok:** A szolgáltatói kvóta kimerült. +**Cause:** Provider quota exhausted. -**Javítás:** +**Fix:** -1. Ellenőrizze az irányítópult kvótakövetőjét -2. Használjon kombót tartalék szintekkel -3. Váltson olcsóbb/ingyenes szintre +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Díjkorlátozás +### Rate Limiting -**Ok:** Az előfizetési kvóta kimerült. +**Cause:** Subscription quota exhausted. -**Javítás:** +**Fix:** -- Tartalék hozzáadása: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Használja a GLM/MiniMax-ot olcsó tartalékként +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth-token lejárt +### OAuth Token Expired -Az OmniRoute automatikusan frissíti a tokeneket. Ha a problémák továbbra is fennállnak: +OmniRoute auto-refreshes tokens. If issues persist: -1. Irányítópult → Szolgáltató → Újracsatlakozás -2. Törölje és adja hozzá újra a szolgáltatói kapcsolatot +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Felhővel kapcsolatos problémák +## Cloud Issues -### Felhőszinkronizálási hibák +### Cloud Sync Errors -1. Ellenőrizze, hogy a futó példány `BASE_URL` pontja (pl. `http://localhost:20128`) -2. Igazoljon `CLOUD_URL` pontot a felhő-végponthoz (pl. `https://omniroute.dev`) -3. Tartsa az `NEXT_PUBLIC_*` értékeket a szerveroldali értékekkel összhangban +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Felhő `stream=false` 500-at tér vissza +### Cloud `stream=false` Returns 500 -**Tünet:** `Unexpected token 'd'...` a felhő-végponton nem streaming hívásokhoz. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Ok:** Az Upstream SSE hasznos adatot ad vissza, miközben az ügyfél a JSON-t várja. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Megkerülő megoldás:** Használja a `stream=true`-t a felhőalapú közvetlen hívásokhoz. A helyi futási környezet tartalmazza az SSE→JSON tartalékot. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### A felhő azt mondja, hogy csatlakoztatva van, de "érvénytelen API-kulcs" +### Cloud Says Connected but "Invalid API key" -1. Hozzon létre egy új kulcsot a helyi irányítópultról (`/api/keys`) -2. Futtassa a felhőszinkronizálást: Engedélyezze a Felhőt → Szinkronizálás most -3. A régi/nem szinkronizált kulcsok továbbra is visszaadhatják a következőt: `401` a felhőben +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Docker problémák +## Docker Issues -### A CLI eszköz azt mutatja, hogy nincs telepítve +### CLI Tool Shows Not Installed -1. Ellenőrizze a futásidejű mezőket: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Hordozható módhoz: használja a `runner-cli` képcélt (csomagolt CLI-k) -3. Gazda beillesztési módhoz: állítsa be a `CLI_EXTRA_PATHS` értéket, és csatlakoztassa a gazdagép bin könyvtárát csak olvashatóként -4. Ha `installed=true` és `runnable=false`: bináris fájl található, de az állapotellenőrzés sikertelen +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Gyors futásidejű érvényesítés +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Költségproblémák +## Cost Issues -### Magas költségek +### High Costs -1. Ellenőrizze a használati statisztikákat az Irányítópult → Használat menüpontban -2. Állítsa át az elsődleges modellt GLM/MiniMax-ra -3. Használjon ingyenes réteget (Gemini CLI, iFlow) a nem kritikus feladatokhoz -4. Állítsa be a költségkereteket API-kulcsonként: Irányítópult → API-kulcsok → Költségvetés +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Hibakeresés +## Debugging -### Kérelemnaplók engedélyezése +### Enable Request Logs -Állítsa be az `ENABLE_REQUEST_LOGS=true` értéket a `.env` fájlban. A naplók a `logs/` könyvtárban jelennek meg. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Ellenőrizze a szolgáltató állapotát +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Futásidejű tárhely +### Runtime Storage -- Fő állapot: `${DATA_DIR}/db.json` (szolgáltatók, kombinációk, álnevek, kulcsok, beállítások) -- Használat: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Kérelemnaplók: `/logs/...` (amikor `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Áramköri megszakítóval kapcsolatos problémák +## Circuit Breaker Issues -### A szolgáltató NYITOTT állapotban ragadt +### Provider stuck in OPEN state -Amikor egy szolgáltató megszakítója NYITVA van, a kérések blokkolva vannak, amíg a leállás le nem jár. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Javítás:** +**Fix:** -1. Lépjen az **Irányítópult → Beállítások → Rugalmasság** menüpontra. -2. Ellenőrizze az érintett szolgáltató megszakítókártyáját -3. Kattintson a **Reset All** elemre az összes megszakító törléséhez, vagy várja meg, amíg a lehűlés lejár -4. A visszaállítás előtt ellenőrizze, hogy a szolgáltató valóban elérhető-e +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### A szolgáltató folyamatosan kioldja a megszakítót +### Provider keeps tripping the circuit breaker -Ha egy szolgáltató ismételten NYITOTT állapotba lép: +If a provider repeatedly enters OPEN state: -1. Ellenőrizze a **Irányítópult → Állapot → Szolgáltató állapota** menüpontban a hibamintát -2. Lépjen a **Beállítások → Ellenállás → Szolgáltatói profilok** menüpontra, és növelje a meghibásodási küszöböt. -3. Ellenőrizze, hogy a szolgáltató megváltoztatta-e az API-korlátokat, vagy nem igényel-e újbóli hitelesítést -4. Tekintse át a késleltetési telemetriát – a magas késleltetés időtúllépésen alapuló hibákat okozhat +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Hangátírási problémák +## Audio Transcription Issues -### "Nem támogatott modell" hiba +### "Unsupported model" error -- Győződjön meg arról, hogy a megfelelő előtagot használja: `deepgram/nova-3` vagy `assemblyai/best` -- Ellenőrizze, hogy a szolgáltató csatlakoztatva van-e az **Irányítópult → Szolgáltatók** menüpontban. +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Az átírás üresen tér vissza, vagy meghiúsul +### Transcription returns empty or fails -- Ellenőrizze a támogatott hangformátumokat: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Ellenőrizze, hogy a fájl mérete a szolgáltatói korlátokon belül van (általában < 25 MB) -- Ellenőrizze a szolgáltatói API kulcs érvényességét a szolgáltatói kártyán +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Fordítói hibakeresés +## Translator Debugging -Használja az **Irányítópult → Fordító** lehetőséget a formátumfordítási problémák elhárításához: +Use **Dashboard → Translator** to debug format translation issues: -| mód | Mikor kell használni | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| **Játszótér** | Hasonlítsa össze a bemeneti/kimeneti formátumokat egymás mellett – illesszen be egy hibás kérést, hogy megtudja, hogyan fordítja le | -| **Csevegés tesztelő** | Küldjön élő üzeneteket, és ellenőrizze a teljes kérés/válasz hasznos adatot, beleértve a fejléceket | -| **Próbapad** | Futtasson kötegelt teszteket a formátumkombinációk között, hogy megtudja, mely fordítások hibásak | -| **Élő monitor** | Nézze meg a valós idejű kérések folyamatát az időszakos fordítási problémák észleléséhez | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Gyakori formátumproblémák +### Common format issues -- **Nem jelennek meg a gondolkodási címkék** — Ellenőrizze, hogy a célszolgáltató támogatja-e a gondolkodást és a gondolkodási költségvetés beállítását -- **Eszközhívások megszakítása** — Egyes formátumfordítások eltávolíthatják a nem támogatott mezőket; ellenőrizze Playground módban -- **Rendszerprompt hiányzik** — Claude és Gemini fogantyúrendszere eltérő módon szól; ellenőrizze a fordítás kimenetét -- **Az SDK nyers karakterláncot ad vissza az objektum helyett** - Javítva az 1.1.0 verzióban: a válasz-fertőtlenítő mostantól eltávolítja azokat a nem szabványos mezőket (`x_groq`, `usage_breakdown` stb.), amelyek az OpenAI SDK Pydantic ellenőrzési hibáit okozzák -- **GLM/ERNIE elutasítja a `system` szerepkört** - Javítva az 1.1.0 verzióban: a szerepnormalizáló automatikusan egyesíti a rendszerüzeneteket felhasználói üzenetekké az inkompatibilis modelleknél -- **`developer` szerepkör nem ismerhető fel** - Javítva az 1.1.0 verzióban: automatikusan `system`-ra konvertálva a nem OpenAI szolgáltatók számára -- **`json_schema` nem működik a Geminivel** - Javítva az 1.1.0-s verzióban: `response_format` mostantól Gemini `responseMimeType` + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Rugalmassági beállítások +## Resilience Settings -### Az automatikus sebességkorlátozás nem aktiválódik +### Auto rate-limit not triggering -- Az automatikus díjkorlát csak az API-kulcs-szolgáltatókra vonatkozik (nem az OAuth-ra/előfizetésre) -- Ellenőrizze, hogy a **Beállítások → Ellenállás → Szolgáltatói profilok** engedélyezve van-e az automatikus díjkorlátozás -- Ellenőrizze, hogy a szolgáltató `429` állapotkódokat vagy `Retry-After` fejlécet ad-e vissza +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Exponenciális visszalépés hangolása +### Tuning exponential backoff -A szolgáltatói profilok az alábbi beállításokat támogatják: +Provider profiles support these settings: -- **Alapkésleltetés** - Kezdeti várakozási idő az első hiba után (alapértelmezett: 1 mp) -- **Maximális késleltetés** - Maximális várakozási idő (alapértelmezett: 30 mp) -- **Szorzó** - Mennyivel növelhető a késleltetés egy egymást követő hiba esetén (alapértelmezett: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Mennydörgés elleni csorda +### Anti-thundering herd -Amikor sok egyidejű kérés ér egy korlátozott sebességű szolgáltatót, az OmniRoute mutex + automatikus sebességkorlátozást használ a kérések sorba rendezésére és a lépcsőzetes hibák megelőzésére. Ez automatikus az API-kulcs-szolgáltatók számára. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Még mindig elakadt? +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub-problémák**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architektúra**: A belső részletekért lásd: [link](ARCHITECTURE.md) -- **API-referencia**: Lásd: [link](API_REFERENCE.md) az összes végponthoz -- **Egészségügyi irányítópult**: Az **Irányítópult → Egészség** menüpontban ellenőrizze a valós idejű rendszerállapotot -- **Fordító**: Használja az **Irányítópult → Fordító** lehetőséget a formátumhibák elhárításához +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/hu/USER_GUIDE.md b/docs/i18n/hu/USER_GUIDE.md index a03d0d94e3..5a043224df 100644 --- a/docs/i18n/hu/USER_GUIDE.md +++ b/docs/i18n/hu/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Használati útmutató +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Teljes útmutató a szolgáltatók konfigurálásához, kombinációk létrehozásához, a CLI-eszközök integrálásához és az OmniRoute telepítéséhez. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Tartalomjegyzék +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Teljes útmutató a szolgáltatók konfigurálásához, kombinációk létrehoz --- -## 💰 Árazás egy pillantásra +## 💰 Pricing at a Glance -| Tier | Szolgáltató | Költség | Kvóta visszaállítása | Legjobb a | -| ----------------- | ------------------ | ----------------------- | ---------------------- | ------------------------------- | -| **💳 ELŐFIZETÉS** | Claude Code (Pro) | 20 USD/hó | 5 óra + heti | Már előfizetett | -| | Codex (Plus/Pro) | 20-200 USD/hó | 5 óra + heti | OpenAI felhasználók | -| | Gemini CLI | **INGYENES** | 180 000/hó + 1 000/nap | Mindenki! | -| | GitHub másodpilóta | 10-19 USD/hó | Havi | GitHub felhasználók | -| **🔑 API KULCS** | DeepSeek | Fizetés használatonként | Nincs | Olcsó érvelés | -| | Groq | Fizetés használatonként | Nincs | Ultragyors következtetés | -| | xAI (Grok) | Fizetés használatonként | Nincs | Grok 4 okfejtés | -| | Mistral | Fizetés használatonként | Nincs | EU-ban működő modellek | -| | Zavartság | Fizetés használatonként | Nincs | Keresés-bővített | -| | Együtt AI | Fizetés használatonként | Nincs | Nyílt forráskódú modellek | -| | Tűzijáték AI | Fizetés használatonként | Nincs | Gyors FLUX képek | -| | Cerebrák | Fizetés használatonként | Nincs | Ostya léptékű sebesség | -| | Cohere | Fizetés használatonként | Nincs | Parancs R+ RAG | -| | NVIDIA NIM | Fizetés használatonként | Nincs | Vállalati modellek | -| **💰 OLCSÓ** | GLM-4.7 | 0,6 USD/1M | Naponta 10:00 | Költségvetési biztonsági mentés | -| | MiniMax M2.1 | 0,2 USD/1M | 5 órás gurulás | Legolcsóbb lehetőség | -| | Kimi K2 | 9 USD/hó lakás | 10 millió token/hó | Előrelátható költség | -| **🆓 INGYENES** | iFlow | $0 | Korlátlan | 8 modell ingyenes | -| | Qwen | $0 | Korlátlan | 3 modell ingyenes | -| | Kiro | $0 | Korlátlan | Claude ingyen | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Pro tipp:** Kezdje a Gemini CLI-vel (180 000 ingyenes/hónap) + iFlow (korlátlan ingyenes) kombináció = 0 USD költség! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Használati esetek +## 🎯 Use Cases -### 1. eset: "Claude Pro előfizetésem van" +### Case 1: "I have Claude Pro subscription" -**Probléma:** A kvóta lejár, kihasználatlanul, sebességkorlátozások erős kódolás közben +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### 2. eset: "Nulla költséget akarok" +### Case 2: "I want zero cost" -**Probléma:** Nem engedheti meg magának az előfizetést, megbízható mesterséges intelligencia kódolásra van szüksége +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### 3. eset: "24 órás kódolásra van szükségem, megszakítás nélkül" +### Case 3: "I need 24/7 coding, no interruptions" -**Probléma:** Határidők, nem engedheti meg magának az állásidőt +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### 4. eset: "INGYENES AI-t akarok az OpenClawban" +### Case 4: "I want FREE AI in OpenClaw" -**Probléma:** AI-asszisztens szükséges az üzenetküldő alkalmazásokhoz, teljesen ingyenes +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Szolgáltató beállítása +## 📖 Provider Setup -### 🔐 Előfizetéses szolgáltatók +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Profi tipp:** Használja az Opust összetett feladatokhoz, a Sonnet pedig a sebességhez. Az OmniRoute nyomkövetési kvóta modellenként! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (INGYENES 180 000/hó!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Legjobb érték:** Hatalmas ingyenes szint! Használja ezt a fizetett szintek előtt. +**Best Value:** Huge free tier! Use this before paid tiers. -#### GitHub másodpilóta +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Olcsó szolgáltatók +### 💰 Cheap Providers -#### GLM-4.7 (napi visszaállítás, 0,6 USD/1 millió) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Regisztráljon: [Zhipu AI](https://open.bigmodel.cn/) -2. Szerezze be az API-kulcsot a Coding Plan-ból -3. Irányítópult → API-kulcs hozzáadása: Szolgáltató: `glm`, API-kulcs: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Használat:** `glm/glm-4.7` — **Profi tipp:** A kódolási terv 3-szoros kvótát kínál 1/7 költséggel! Visszaállítás naponta 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 óra visszaállítás, 0,20 USD/1 millió) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Regisztráljon: [MiniMax](https://www.minimax.io/) -2. API-kulcs lekérése → Irányítópult → API-kulcs hozzáadása +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Használat:** `minimax/MiniMax-M2.1` — **Profi tipp:** A legolcsóbb lehetőség hosszú kontextushoz (1 millió token)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (9 USD/hó lakás) +#### Kimi K2 ($9/month flat) -1. Feliratkozás: [Moonshot AI](https://platform.moonshot.ai/) -2. API-kulcs lekérése → Irányítópult → API-kulcs hozzáadása +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Használat:** `kimi/kimi-latest` — **Profi tipp:** Fix 9 USD/hó 10 millió tokenek esetén = 0,90 USD/1 millió tényleges költség! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 INGYENES szolgáltatók +### 🆓 FREE Providers -#### iFlow (8 INGYENES modell) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 INGYENES modell) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude INGYENES) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 kombók +## 🎨 Combos -### 1. példa: Előfizetés maximalizálása → Olcsó biztonsági mentés +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### 2. példa: Csak ingyenes (nulla költség) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI integráció +## 🔧 CLI Integration -### Kurzor IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -262,7 +262,7 @@ Settings → Models → Advanced: ### Claude Code -`~/.claude/config.json` szerkesztése: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -`~/.openclaw/openclaw.json` szerkesztése: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ codex "your prompt" } ``` -**Vagy használja az Irányítópultot:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Folytatás / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Bevezetés +## 🚀 Deployment -### VPS telepítés +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -A CLI binárisokkal rendelkező gazdagépbe integrált módhoz lásd a Docker szakaszt a fő dokumentumokban. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Környezeti változók +### Environment Variables -| Változó | Alapértelmezett | Leírás | -| --------------------- | ------------------------------------ | --------------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT aláírási titok (**változás a gyártásban**) | -| `INITIAL_PASSWORD` | `123456` | Első bejelentkezési jelszó | -| `DATA_DIR` | `~/.omniroute` | Adatkönyvtár (db, használat, naplók) | -| `PORT` | keretrendszer alapértelmezett | Szervizport (`20128` a példákban) | -| `HOSTNAME` | keretrendszer alapértelmezett | Gazda kötése (a Docker alapértelmezett értéke `0.0.0.0`) | -| `NODE_ENV` | futásidejű alapértelmezett | Állítsa be az `production` értéket a telepítéshez | -| `BASE_URL` | `http://localhost:20128` | Szerveroldali belső alap URL | -| `CLOUD_URL` | `https://omniroute.dev` | Felhőszinkronizálási végpont alap URL-je | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC titkos a generált API-kulcsokhoz | -| `REQUIRE_API_KEY` | `false` | Bearer API kulcs kényszerítése a következőn: `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Engedélyezi a kérés/válasz naplózást | -| `AUTH_COOKIE_SECURE` | `false` | `Secure` hitelesítési cookie kényszerítése (a HTTPS fordított proxy mögött) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -A teljes környezeti változó hivatkozását lásd: [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Elérhető modellek +## 📊 Available Models
-Az összes elérhető modell megtekintése +View all available models **Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Kód (`cx/`)** – Plusz/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** – INGYENES: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**GitHub másodpilóta (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** – 0,6 USD/1 millió: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** – 0,2 USD/1 millió: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** – INGYENES: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** – INGYENES: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** – INGYENES: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,13 +460,13 @@ A teljes környezeti változó hivatkozását lásd: [README](../README.md). **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Zavarság (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Együtt AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` **Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Agy (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` **Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` @@ -417,11 +476,11 @@ A teljes környezeti változó hivatkozását lásd: [README](../README.md). --- -## 🧩 Speciális funkciók +## 🧩 Advanced Features -### Egyedi modellek +### Custom Models -Adjon hozzá bármilyen modellazonosítót bármely szolgáltatóhoz anélkül, hogy az alkalmazás frissítésére várna: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Vagy használja az Irányítópultot: **Providers → [Provider] → Custom Models**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Dedikált szolgáltatói útvonalak +### Dedicated Provider Routes -A kérések közvetlenül egy adott szolgáltatóhoz irányíthatók modellellenőrzéssel: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -A szolgáltató előtagja automatikusan hozzáadódik, ha hiányzik. A nem egyező modellek a következőt adják vissza: `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Hálózati proxy konfiguráció +### Network Proxy Configuration ```bash # Set global proxy @@ -463,7 +522,7 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Precencia:** Kulcsspecifikus → Kombinált → Szolgáltató-specifikus → Globális → Környezet. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. ### Model Catalog API @@ -471,68 +530,68 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ curl http://localhost:20128/api/models/catalog ``` -A modelleket szolgáltató szerint csoportosítva adja vissza típusokkal (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). ### Cloud Sync -- Szinkronizálja a szolgáltatókat, kombinációkat és beállításokat az eszközök között -- Automatikus háttérszinkronizálás időtúllépéssel + hibamentes -- Szerveroldali `BASE_URL`/`CLOUD_URL` előnyben részesítése éles környezetben +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (9. fázis) +### LLM Gateway Intelligence (Phase 9) -- **Szemantikus gyorsítótár** – Automatikus gyorsítótárak, nem streamelés, hőmérséklet = 0 válasz (kihagyás a `X-OmniRoute-No-Cache: true` segítségével) -- **Idempotency kérése** – 5 másodpercen belül deduplikálja a kéréseket a `Idempotency-Key` vagy `X-Request-Id` fejlécen keresztül -- **Előrehaladás követése** — SSE `event: progress` események engedélyezése a `X-OmniRoute-Progress: true` fejlécen keresztül +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Fordítói Játszótér +### Translator Playground -Hozzáférés az **Irányítópult → Fordító** segítségével. Hibakeresés és vizualizálás, hogy az OmniRoute hogyan fordítja le az API-kéréseket a szolgáltatók között. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| mód | Cél | -| --------------------- | ---------------------------------------------------------------------------------------------------------------- | -| **Játszótér** | Válassza ki a forrás-/célformátumokat, illesszen be egy kérést, és azonnal megtekintheti a lefordított kimenetet | -| **Csevegés tesztelő** | Küldjön élő csevegési üzeneteket a proxyn keresztül, és ellenőrizze a teljes kérés/válasz ciklust | -| **Próbapad** | Futtasson kötegelt teszteket több formátumkombinációra a fordítás helyességének ellenőrzéséhez | -| **Élő monitor** | Nézze meg a valós idejű fordításokat, ahogy a kérések a proxyn keresztül áramlanak | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Használati esetek:** +**Use cases:** -- Hibakeresés, miért nem sikerül egy adott ügyfél/szolgáltató kombináció -- Ellenőrizze, hogy a gondolkodó címkék, az eszközhívások és a rendszerkérések helyesen fordítódnak-e -- Hasonlítsa össze a formátumbeli különbségeket az OpenAI, Claude, Gemini és Responses API formátumok között +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Útválasztási stratégiák +### Routing Strategies -Konfigurálás a **Irányítópult → Beállítások → Útválasztás** menüpontban. +Configure via **Dashboard → Settings → Routing**. -| Stratégia | Leírás | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | -| **Először töltse ki** | A fiókokat prioritási sorrendben használja – az elsődleges fiók minden kérést kezel, amíg el nem éri | -| **Round Robin** | A konfigurálható ragadós korláttal rendelkező összes fiókot végigjárja (alapértelmezett: fiókonként 3 hívás) | -| **P2C (Power of Two Choices)** | 2 véletlenszerű fiókot választ, és az egészségesebbhez vezet – egyensúlyba hozza a terhelést az egészségtudattal | -| **Véletlen** | Véletlenszerűen kiválaszt egy fiókot minden egyes kérelemhez a Fisher-Yates shuffle | -| **Legkevésbé használt** | Útvonalak a legrégebbi `lastUsedAt` időbélyeggel rendelkező fiókhoz, a forgalom egyenletes elosztása | -| **Költségoptimalizált** | Útvonalak a legalacsonyabb prioritású fiókhoz, a legalacsonyabb költségű szolgáltatókra optimalizálva | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Helyettesítő modell álnevek +#### Wildcard Model Aliases -Hozzon létre helyettesítő karakteres mintákat a modellnevek újratervezéséhez: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -A helyettesítő karakterek támogatják a `*` (bármilyen karakter) és az `?` (egykarakteres). +Wildcards support `*` (any characters) and `?` (single character). -#### Tartalékláncok +#### Fallback Chains -Határozzon meg globális tartalék láncokat, amelyek minden kérelemre vonatkoznak: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Rugalmasság és megszakítók +### Resilience & Circuit Breakers -Konfigurálás a **Irányítópult → Beállítások → Ellenállás** menüpontban. +Configure via **Dashboard → Settings → Resilience**. -Az OmniRoute szolgáltatói szintű rugalmasságot valósít meg négy összetevőből: +OmniRoute implements provider-level resilience with four components: -1. **Szolgáltatói profilok** — Szolgáltatónkénti konfiguráció a következőkhöz: - - Meghibásodási küszöb (hány hiba történt a nyitás előtt) - - Lehűlés időtartama - - Sebességkorlát érzékelési érzékenység - - Exponenciális backoff paraméterek +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Szerkeszthető díjkorlátok** — Az irányítópulton konfigurálható rendszerszintű alapértékek: - - **Percenkénti kérések (RPM)** – A percenkénti kérések száma fiókonként - - **Minimális idő a kérések között** - Minimális eltérés ezredmásodpercben a kérések között - - **Maximális egyidejű kérések** - Maximális egyidejű kérések száma fiókonként - - Kattintson a **Szerkesztés** gombra a módosításhoz, majd a **Mentés** vagy a **Mégse** gombra. Az értékek a rezilience API-n keresztül megmaradnak. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** – Nyomon követi a hibákat szolgáltatónként, és automatikusan megnyitja az áramkört egy küszöbérték elérésekor: - - **ZÁRVA** (egészséges) – A kérések normálisan futnak - - **NYITVA** — A szolgáltató ideiglenesen blokkolva van ismétlődő hibák után - - **HALF_OPEN** — Tesztelés, hogy a szolgáltató helyreállt-e +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Policies & Locked Identifiers** — Megjeleníti a megszakító állapotát és a zárolt azonosítókat kényszer-feloldási képességgel. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Díjkorlát automatikus észlelése** – Figyeli a `429` és `Retry-After` fejléceket, hogy proaktívan elkerülje a szolgáltatói díjkorlátok átlépését. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Profi tipp:** Használja a **Reset All** gombot az összes megszakító és leállás törléséhez, amikor a szolgáltató felépül egy kiesésből. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Adatbázis exportálása/importálása +### Database Export / Import -Az adatbázis-mentéseket az **Irányítópult → Beállítások → Rendszer és tárhely** menüpontban kezelheti. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Akció | Leírás | -| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Adatbázis exportálása** | Letölti az aktuális SQLite adatbázist `.sqlite` fájlként | -| **Az összes exportálása (.tar.gz)** | Letölt egy teljes biztonsági másolat archívumot, beleértve: adatbázist, beállításokat, kombinációkat, szolgáltatói kapcsolatokat (hitelesítő adatok nélkül), API kulcs metaadatait | -| **Adatbázis importálása** | Töltsön fel egy `.sqlite` fájlt az aktuális adatbázis lecseréléséhez. Az importálás előtti biztonsági másolat automatikusan létrejön | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Importálás ellenőrzése:** Az importált fájl integritását (SQLite pragma ellenőrzés), a szükséges táblákat (`provider_connections`, `provider_nodes`, `combos`, ) és 0 MB-ot (0 MB_x ) ellenőrzik. +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Használati esetek:** +**Use Cases:** -- Az OmniRoute áttelepítése a gépek között -- Készítsen külső biztonsági másolatot a katasztrófa utáni helyreállításhoz -- A konfigurációk megosztása a csapattagok között (összes exportálása → archívum megosztása) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Beállítások irányítópultja +### Settings Dashboard -A beállítási oldal 5 lapra van felosztva a könnyű navigáció érdekében: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Tartalom | -| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| **Biztonság** | Bejelentkezés/jelszó beállítások, IP-hozzáférés-vezérlés, API-hitelesítés a `/models`-hoz és Szolgáltató blokkolása | -| **Útválasztás** | Globális útválasztási stratégia (6 lehetőség), helyettesítő karakteres modellálnevek, tartalék láncok, kombinált alapértelmezések | -| **rugalmasság** | Szolgáltatói profilok, szerkeszthető sebességkorlátok, megszakító állapota, szabályzatok és zárolt azonosítók | -| **AI** | Átgondolt költségkeret-konfiguráció, globális rendszerbefecskendezés, gyorsítótár-statisztikák | -| **Speciális** | Globális proxykonfiguráció (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Költségek és költségvetés kezelése +### Costs & Budget Management -Hozzáférés az **Irányítópult → Költségek** menüponton keresztül. +Access via **Dashboard → Costs**. -| Tab | Cél | -| ---------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **Költségvetés** | Költési korlátok beállítása API-kulcsonként napi/heti/havi költségkerettel és valós idejű követéssel | -| **Árak** | Modellárazási bejegyzések megtekintése és szerkesztése – szolgáltatónként 1 000 bemeneti/kimeneti tokenenkénti költség | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Költségkövetés:** Minden kérés naplózza a tokenhasználatot, és az ártáblázat segítségével kiszámítja a költségeket. Tekintse meg az **Irányítópult → Használat** szolgáltató, modell és API-kulcs szerinti lebontását. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Hangátírás +### Audio Transcription -Az OmniRoute támogatja a hang átírását az OpenAI-kompatibilis végponton keresztül: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Elérhető szolgáltatók: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Támogatott hangformátumok: `mp3`, `wav`, `m4a`, `flac`, `ogg`, +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Kombinált egyensúlyozási stratégiák +### Combo Balancing Strategies -Konfigurálja a kombinált egyensúlyozást az **Irányítópult → Kombók → Létrehozás/Szerkesztés → Stratégia** menüpontban. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Stratégia | Leírás | -| ----------------------- | ------------------------------------------------------------------------------------------------ | -| **Round-Robin** | Sorozatosan forgatja a modelleket | -| **Prioritás** | Mindig az első modellt próbálja ki; csak hibára esik vissza | -| **Véletlen** | Véletlenszerű modellt választ a kombinációból minden egyes kéréshez | -| **Súlyozott** | Útvonalak arányosan a modellenként hozzárendelt súlyok alapján | -| **Legkevésbé használt** | Útvonalak a legutóbbi legkevesebb kéréssel rendelkező modellhez (kombinált mérőszámokat használ) | -| **Költségoptimalizált** | Útvonalak a legolcsóbb elérhető modellhez (árazási táblázatot használ) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -A globális kombinált alapértelmezések az **Irányítópult → Beállítások → Útválasztás → Kombinált alapértelmezések** menüpontban állíthatók be. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Egészségügyi irányítópult +### Health Dashboard -Hozzáférés az **Irányítópult → Egészség** menüponton keresztül. Valós idejű rendszerállapot-áttekintés 6 kártyával: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Kártya | Mit mutat | -| ------------------------- | ---------------------------------------------------------------------- | -| **Rendszerállapot** | Üzemidő, verzió, memóriahasználat, adatkönyvtár | -| **Szolgáltatói egészség** | Szolgáltatónkénti megszakító állapota (Zárt/Nyitott/Félig nyitva) | -| **Díjkorlátok** | Aktív sebességkorlátozások fiókonként a hátralévő idővel | -| **Aktív kizárások** | A kizárási szabályzat által ideiglenesen letiltott szolgáltatók | -| **Aláírás-gyorsítótár** | Deduplikációs gyorsítótár statisztikái (aktív kulcsok, találati arány) | -| **Latencia telemetria** | p50/p95/p99 késleltetési összesítés szolgáltatónként | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Profi tipp:** Az Egészség oldal 10 másodpercenként automatikusan frissül. Használja a megszakító kártyát annak azonosítására, hogy mely szolgáltatók tapasztaltak problémákat. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/id/API_REFERENCE.md b/docs/i18n/id/API_REFERENCE.md index 4873a109e7..b795722c11 100644 --- a/docs/i18n/id/API_REFERENCE.md +++ b/docs/i18n/id/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Referensi API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Referensi lengkap untuk semua titik akhir OmniRoute API. +Complete reference for all OmniRoute API endpoints. --- -## Daftar Isi +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Referensi lengkap untuk semua titik akhir OmniRoute API. --- -## Penyelesaian Obrolan +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Header Khusus +### Custom Headers -| Tajuk | Arah | Deskripsi | -| ------------------------ | ---------- | -------------------------------------- | -| `X-OmniRoute-No-Cache` | Permintaan | Setel ke `true` untuk melewati cache | -| `X-OmniRoute-Progress` | Permintaan | Setel ke `true` untuk acara kemajuan | -| `Idempotency-Key` | Permintaan | Kunci Dedup (jendela 5 detik) | -| `X-Request-Id` | Permintaan | Kunci dedup alternatif | -| `X-OmniRoute-Cache` | Tanggapan | `HIT` atau `MISS` (non-streaming) | -| `X-OmniRoute-Idempotent` | Tanggapan | `true` jika duplikatnya | -| `X-OmniRoute-Progress` | Tanggapan | `enabled` jika pelacakan kemajuan pada | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Penyematan +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Penyedia yang tersedia: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Pembuatan Gambar +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Penyedia yang tersedia: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Daftar Model +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Titik Akhir Kompatibilitas +## Compatibility Endpoints -| Metode | Jalur | Format | -| -------- | --------------------------- | -------------------------- | -| POSTING | `/v1/chat/completions` | OpenAI | -| POSTING | `/v1/messages` | Antropik | -| POSTING | `/v1/responses` | Tanggapan OpenAI | -| POSTING | `/v1/embeddings` | OpenAI | -| POSTING | `/v1/images/generations` | OpenAI | -| DAPATKAN | `/v1/models` | OpenAI | -| POSTING | `/v1/messages/count_tokens` | Antropik | -| DAPATKAN | `/v1beta/models` | kembar | -| POSTING | `/v1beta/models/{...path}` | Gemini menghasilkan Konten | -| POSTING | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Rute Penyedia Khusus +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Awalan penyedia ditambahkan secara otomatis jika tidak ada. Model yang tidak cocok menampilkan `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Cache Semantik +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Contoh tanggapan: +Response example: ```json { @@ -162,154 +162,164 @@ Contoh tanggapan: --- -## Dasbor & Manajemen +## Dashboard & Management -### Otentikasi +### Authentication -| Titik akhir | Metode | Deskripsi | -| ----------------------------- | ----------------- | ------------------------ | -| `/api/auth/login` | POSTING | Masuk | -| `/api/auth/logout` | POSTING | Keluar | -| `/api/settings/require-login` | DAPATKAN/MASUKKAN | Beralih login diperlukan | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Manajemen Penyedia +### Provider Management -| Titik akhir | Metode | Deskripsi | -| ---------------------------- | ----------------------- | ----------------------------- | -| `/api/providers` | DAPATKAN/POSTING | Daftar / buat penyedia | -| `/api/providers/[id]` | DAPATKAN/MASUKKAN/HAPUS | Kelola penyedia | -| `/api/providers/[id]/test` | POSTING | Koneksi penyedia tes | -| `/api/providers/[id]/models` | DAPATKAN | Daftar model penyedia | -| `/api/providers/validate` | POSTING | Validasi konfigurasi penyedia | -| `/api/provider-nodes*` | Berbagai | Manajemen node penyedia | -| `/api/provider-models` | DAPATKAN/POSTING/HAPUS | Model khusus | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Alur OAuth +### OAuth Flows -| Titik akhir | Metode | Deskripsi | -| -------------------------------- | -------- | --------------------- | -| `/api/oauth/[provider]/[action]` | Berbagai | OAuth khusus penyedia | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Perutean & Konfigurasi +### Routing & Config -| Titik akhir | Metode | Deskripsi | -| --------------------- | ---------------- | --------------------------------------- | -| `/api/models/alias` | DAPATKAN/POSTING | Alias ​​model | -| `/api/models/catalog` | DAPATKAN | Semua model berdasarkan penyedia + tipe | -| `/api/combos*` | Berbagai | Manajemen kombo | -| `/api/keys*` | Berbagai | Manajemen kunci API | -| `/api/pricing` | DAPATKAN | Penetapan harga model | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Penggunaan & Analisis +### Usage & Analytics -| Titik akhir | Metode | Deskripsi | -| --------------------------- | -------- | ---------------------- | -| `/api/usage/history` | DAPATKAN | Riwayat penggunaan | -| `/api/usage/logs` | DAPATKAN | Log penggunaan | -| `/api/usage/request-logs` | DAPATKAN | Log tingkat permintaan | -| `/api/usage/[connectionId]` | DAPATKAN | Penggunaan per koneksi | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Pengaturan +### Settings -| Titik akhir | Metode | Deskripsi | -| ------------------------------- | ----------------- | -------------------------------------- | -| `/api/settings` | DAPATKAN/MASUKKAN | Pengaturan umum | -| `/api/settings/proxy` | DAPATKAN/MASUKKAN | Konfigurasi proksi jaringan | -| `/api/settings/proxy/test` | POSTING | Uji koneksi proxy | -| `/api/settings/ip-filter` | DAPATKAN/MASUKKAN | Daftar IP yang diizinkan/daftar blokir | -| `/api/settings/thinking-budget` | DAPATKAN/MASUKKAN | Penalaran anggaran token | -| `/api/settings/system-prompt` | DAPATKAN/MASUKKAN | Perintah sistem global | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Pemantauan +### Monitoring -| Titik akhir | Metode | Deskripsi | -| ------------------------ | -------------- | ----------------------- | -| `/api/sessions` | DAPATKAN | Pelacakan sesi aktif | -| `/api/rate-limits` | DAPATKAN | Batas tarif per akun | -| `/api/monitoring/health` | DAPATKAN | Pemeriksaan kesehatan | -| `/api/cache` | DAPATKAN/HAPUS | Statistik cache / hapus | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Cadangkan & Ekspor/Impor +### Backup & Export/Import -| Titik akhir | Metode | Deskripsi | -| --------------------------- | -------- | ----------------------------------------------- | -| `/api/db-backups` | DAPATKAN | Daftar cadangan yang tersedia | -| `/api/db-backups` | TETAPKAN | Buat cadangan manual | -| `/api/db-backups` | POSTING | Pulihkan dari cadangan tertentu | -| `/api/db-backups/export` | DAPATKAN | Unduh database sebagai file .sqlite | -| `/api/db-backups/import` | POSTING | Unggah file .sqlite untuk menggantikan database | -| `/api/db-backups/exportAll` | DAPATKAN | Unduh cadangan lengkap sebagai arsip .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Sinkronisasi Awan +### Cloud Sync -| Titik akhir | Metode | Deskripsi | -| ---------------------- | -------- | -------------------------- | -| `/api/sync/cloud` | Berbagai | Operasi sinkronisasi cloud | -| `/api/sync/initialize` | POSTING | Inisialisasi sinkronisasi | -| `/api/cloud/*` | Berbagai | Manajemen awan | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Alat CLI +### CLI Tools -| Titik akhir | Metode | Deskripsi | -| ---------------------------------- | -------- | ------------------------ | -| `/api/cli-tools/claude-settings` | DAPATKAN | Status Claude CLI | -| `/api/cli-tools/codex-settings` | DAPATKAN | Status CLI Kodeks | -| `/api/cli-tools/droid-settings` | DAPATKAN | Status CLI Droid | -| `/api/cli-tools/openclaw-settings` | DAPATKAN | Status CLI OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | DAPATKAN | Waktu proses CLI generik | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Respons CLI meliputi: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Ketahanan & Batas Nilai +### ACP Agents -| Titik akhir | Metode | Deskripsi | -| ----------------------- | ----------------- | ---------------------------------- | -| `/api/resilience` | DAPATKAN/MASUKKAN | Dapatkan/perbarui profil ketahanan | -| `/api/resilience/reset` | POSTING | Setel ulang pemutus sirkuit | -| `/api/rate-limits` | DAPATKAN | Status batas tarif per akun | -| `/api/rate-limit` | DAPATKAN | Konfigurasi batas tarif global | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Evaluasi +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Titik akhir | Metode | Deskripsi | -| ------------ | ---------------- | ------------------------------------ | -| `/api/evals` | DAPATKAN/POSTING | Daftar eval suites/jalankan evaluasi | +### Resilience & Rate Limits -### Kebijakan +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Titik akhir | Metode | Deskripsi | -| --------------- | ---------------------- | ------------------------- | -| `/api/policies` | DAPATKAN/POSTING/HAPUS | Kelola kebijakan perutean | +### Evals -### Kepatuhan +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Titik akhir | Metode | Deskripsi | -| --------------------------- | -------- | -------------------------------- | -| `/api/compliance/audit-log` | DAPATKAN | Log audit kepatuhan (N terakhir) | +### Policies -### v1beta (Kompatibel dengan Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Titik akhir | Metode | Deskripsi | -| -------------------------- | -------- | ------------------------------------ | -| `/v1beta/models` | DAPATKAN | Daftar model dalam format Gemini | -| `/v1beta/models/{...path}` | POSTING | Titik akhir Gemini `generateContent` | +### Compliance -Titik akhir ini mencerminkan format API Gemini untuk klien yang mengharapkan kompatibilitas asli Gemini SDK. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### API Internal/Sistem +### v1beta (Gemini-Compatible) -| Titik akhir | Metode | Deskripsi | -| --------------- | -------- | -------------------------------------------------------------------------- | -| `/api/init` | DAPATKAN | Pemeriksaan inisialisasi aplikasi (digunakan saat pertama kali dijalankan) | -| `/api/tags` | DAPATKAN | Tag model yang kompatibel dengan Ollama (untuk klien Ollama) | -| `/api/restart` | POSTING | Memicu restart server dengan anggun | -| `/api/shutdown` | POSTING | Memicu penutupan server dengan baik | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Catatan:** Titik akhir ini digunakan secara internal oleh sistem atau untuk kompatibilitas klien Ollama. Mereka biasanya tidak dipanggil oleh pengguna akhir. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Transkripsi Audio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transkripsikan file audio menggunakan Deepgram atau AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Permintaan:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Respon:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Penyedia yang didukung:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Format yang didukung:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Kompatibilitas Ollama +## Ollama Compatibility -Untuk klien yang menggunakan format API Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Permintaan secara otomatis diterjemahkan antara Ollama dan format internal. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetri +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Respon:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Anggaran +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Ketersediaan Model +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Pemrosesan Permintaan +## Request Processing -1. Klien mengirimkan permintaan ke `/v1/*` -2. Pengendali rute memanggil `handleChat`, `handleEmbedding`, `handleAudioTranscription`, atau `handleImageGeneration` -3. Model terselesaikan (penyedia/model langsung atau alias/kombo) -4. Kredensial dipilih dari DB lokal dengan pemfilteran ketersediaan akun -5. Untuk obrolan: `handleChatCore` — deteksi format, terjemahan, pemeriksaan cache, pemeriksaan idempotensi -6. Pelaksana penyedia mengirimkan permintaan upstream -7. Respons diterjemahkan kembali ke format klien (obrolan) atau dikembalikan apa adanya (embeddings/images/audio) -8. Penggunaan/logging dicatat -9. Fallback berlaku pada error sesuai dengan aturan kombo +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Referensi arsitektur lengkap: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Otentikasi +## Authentication -- Rute dasbor (`/dashboard/*`) menggunakan cookie `auth_token` -- Login menggunakan hash kata sandi yang disimpan; mundur ke `INITIAL_PASSWORD` -- `requireLogin` dapat dialihkan melalui `/api/settings/require-login` -- Rute `/v1/*` secara opsional memerlukan kunci API Pembawa ketika `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/id/ARCHITECTURE.md b/docs/i18n/id/ARCHITECTURE.md index 7efab327f9..258d62df53 100644 --- a/docs/i18n/id/ARCHITECTURE.md +++ b/docs/i18n/id/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Arsitektur OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Terakhir diperbarui: 18-02-2026_ +_Last updated: 2026-03-04_ -## Ringkasan Eksekutif +## Executive Summary -OmniRoute adalah gateway dan dasbor perutean AI lokal yang dibangun di Next.js. -Ini menyediakan satu titik akhir yang kompatibel dengan OpenAI (`/v1/*`) dan merutekan lalu lintas di beberapa penyedia upstream dengan terjemahan, fallback, penyegaran token, dan pelacakan penggunaan. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Kemampuan inti: +Core capabilities: -- Permukaan API yang kompatibel dengan OpenAI untuk CLI/alat (28 penyedia) -- Permintaan/tanggapan terjemahan lintas format penyedia -- Model kombo fallback (urutan multi-model) -- Penggantian tingkat akun (multi-akun per penyedia) -- Manajemen koneksi penyedia kunci OAuth + API -- Menyematkan generasi melalui `/v1/embeddings` (6 penyedia, 9 model) -- Pembuatan gambar melalui `/v1/images/generations` (4 penyedia, 9 model) -- Pikirkan penguraian tag (`...`) untuk model penalaran -- Sanitasi respons untuk kompatibilitas OpenAI SDK yang ketat -- Normalisasi peran (pengembang→sistem, sistem→pengguna) untuk kompatibilitas lintas penyedia -- Konversi keluaran terstruktur (json_schema → Gemini responSchema) -- Persistensi lokal untuk penyedia, kunci, alias, kombo, pengaturan, harga -- Pelacakan penggunaan/biaya dan pencatatan permintaan -- Sinkronisasi cloud opsional untuk sinkronisasi multi-perangkat/negara -- Daftar IP yang diizinkan/daftar blokir untuk kontrol akses API -- Memikirkan manajemen anggaran (passthrough/otomatis/custom/adaptif) -- Injeksi cepat sistem global -- Pelacakan sesi dan sidik jari -- Pembatasan tarif yang ditingkatkan per akun dengan profil khusus penyedia -- Pola pemutus sirkuit untuk ketahanan penyedia -- Perlindungan kawanan anti guntur dengan penguncian mutex -- Cache deduplikasi permintaan berbasis tanda tangan -- Lapisan domain: ketersediaan model, aturan biaya, kebijakan fallback, kebijakan lockout -- Persistensi status domain (cache tulis SQLite untuk fallback, anggaran, penguncian, pemutus sirkuit) -- Mesin kebijakan untuk evaluasi permintaan terpusat (lockout → anggaran → fallback) -- Minta telemetri dengan agregasi latensi p50/p95/p99 -- ID Korelasi (X-Request-Id) untuk penelusuran ujung ke ujung -- Pencatatan audit kepatuhan dengan opt-out per kunci API -- Kerangka evaluasi untuk penjaminan mutu LLM -- Dasbor UI ketahanan dengan status pemutus sirkuit waktu nyata -- Penyedia OAuth modular (12 modul individual di bawah `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Model waktu proses utama: +Primary runtime model: -- Rute aplikasi Next.js di bawah `src/app/api/*` mengimplementasikan API dasbor dan API kompatibilitas -- Inti SSE/perutean bersama di `src/sse/*` + `open-sse/*` menangani eksekusi, terjemahan, streaming, fallback, dan penggunaan penyedia +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Ruang Lingkup dan Batasan +## Scope and Boundaries -### Dalam Cakupan +### In Scope -- Waktu aktif gateway lokal -- API manajemen dasbor -- Otentikasi penyedia dan penyegaran token -- Minta terjemahan dan streaming SSE -- Status lokal + persistensi penggunaan -- Orkestrasi sinkronisasi cloud opsional +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Di Luar Cakupan +### Out of Scope -- Implementasi layanan cloud di belakang `NEXT_PUBLIC_CLOUD_URL` -- Penyedia SLA/bidang kontrol di luar proses lokal -- Biner CLI eksternal itu sendiri (Claude CLI, Codex CLI, dll.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Konteks Sistem Tingkat Tinggi +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Komponen Waktu Proses Inti +## Core Runtime Components -## 1) API dan Lapisan Perutean (Rute Aplikasi Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Direktori utama: +Main directories: -- `src/app/api/v1/*` dan `src/app/api/v1beta/*` untuk API kompatibilitas -- `src/app/api/*` untuk API manajemen/konfigurasi -- Selanjutnya penulisan ulang di `next.config.mjs` peta `/v1/*` menjadi `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Rute kompatibilitas penting: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — termasuk model khusus dengan `custom: true` -- `src/app/api/v1/embeddings/route.ts` — generasi penyematan (6 penyedia) -- `src/app/api/v1/images/generations/route.ts` — pembuatan gambar (4+ penyedia termasuk Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — obrolan khusus per penyedia -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — penyematan khusus per penyedia -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — gambar khusus per penyedia +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Domain manajemen: +Management domains: -- Otentikasi/pengaturan: `src/app/api/auth/*`, `src/app/api/settings/*` -- Penyedia/koneksi: `src/app/api/providers*` -- Node penyedia: `src/app/api/provider-nodes*` -- Model khusus: `src/app/api/provider-models` (GET/POST/DELETE) -- Katalog model: `src/app/api/models/catalog` (GET) -- Konfigurasi proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Kunci/alias/kombo/harga: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Penggunaan: `src/app/api/usage/*` -- Sinkronisasi/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Pembantu perkakas CLI: `src/app/api/cli-tools/*` -- Filter IP: `src/app/api/settings/ip-filter` (DAPATKAN/PUT) -- Memikirkan anggaran: `src/app/api/settings/thinking-budget` (GET/PUT) -- Perintah sistem: `src/app/api/settings/system-prompt` (GET/PUT) -- Sesi: `src/app/api/sessions` (DAPATKAN) -- Batas tarif: `src/app/api/rate-limits` (GET) -- Ketahanan: `src/app/api/resilience` (GET/PATCH) — profil penyedia, pemutus sirkuit, status batas kecepatan -- Reset ketahanan: `src/app/api/resilience/reset` (POST) — reset pemutus + cooldown -- Statistik cache: `src/app/api/cache/stats` (DAPATKAN/HAPUS) -- Ketersediaan model: `src/app/api/models/availability` (GET/POST) -- Telemetri: `src/app/api/telemetry/summary` (GET) -- Anggaran: `src/app/api/usage/budget` (DAPATKAN/POST) -- Rantai cadangan: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Audit kepatuhan: `src/app/api/compliance/audit-log` (GET) -- Nilai: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Kebijakan: `src/app/api/policies` (DAPATKAN/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Inti Terjemahan +## 2) SSE + Translation Core -Modul aliran utama: +Main flow modules: -- Entri: `src/sse/handlers/chat.ts` -- Orkestrasi inti: `open-sse/handlers/chatCore.ts` -- Adaptor eksekusi penyedia: `open-sse/executors/*` -- Deteksi format/konfigurasi penyedia: `open-sse/services/provider.ts` -- Model penguraian/penyelesaian: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Logika penggantian akun: `open-sse/services/accountFallback.ts` -- Registri terjemahan: `open-sse/translator/index.ts` -- Transformasi aliran: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Ekstraksi/normalisasi penggunaan: `open-sse/utils/usageTracking.ts` -- Pikirkan pengurai tag: `open-sse/utils/thinkTagParser.ts` -- Pengendali penyematan: `open-sse/handlers/embeddings.ts` -- Menanamkan registri penyedia: `open-sse/config/embeddingRegistry.ts` -- Pengendali pembuatan gambar: `open-sse/handlers/imageGeneration.ts` -- Registri penyedia gambar: `open-sse/config/imageRegistry.ts` -- Sanitasi respons: `open-sse/handlers/responseSanitizer.ts` -- Normalisasi peran: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Layanan (logika bisnis): +Services (business logic): -- Pemilihan/penilaian akun: `open-sse/services/accountSelector.ts` -- Manajemen siklus hidup konteks: `open-sse/services/contextManager.ts` -- Penegakan filter IP: `open-sse/services/ipFilter.ts` -- Pelacakan sesi: `open-sse/services/sessionManager.ts` -- Permintaan deduplikasi: `open-sse/services/signatureCache.ts` -- Injeksi cepat sistem: `open-sse/services/systemPrompt.ts` -- Memikirkan pengelolaan anggaran: `open-sse/services/thinkingBudget.ts` -- Perutean model karakter pengganti: `open-sse/services/wildcardRouter.ts` -- Manajemen batas tarif: `open-sse/services/rateLimitManager.ts` -- Pemutus arus: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Modul lapisan domain: +Domain layer modules: -- Ketersediaan model: `src/lib/domain/modelAvailability.ts` -- Aturan biaya/anggaran: `src/lib/domain/costRules.ts` -- Kebijakan penggantian: `src/lib/domain/fallbackPolicy.ts` -- Penyelesai kombo: `src/lib/domain/comboResolver.ts` -- Kebijakan penguncian: `src/lib/domain/lockoutPolicy.ts` -- Mesin kebijakan: `src/domain/policyEngine.ts` — penguncian terpusat → anggaran → evaluasi cadangan -- Katalog kode kesalahan: `src/lib/domain/errorCodes.ts` -- ID Permintaan: `src/lib/domain/requestId.ts` -- Batas waktu pengambilan: `src/lib/domain/fetchTimeout.ts` -- Permintaan telemetri: `src/lib/domain/requestTelemetry.ts` -- Kepatuhan/audit: `src/lib/domain/compliance/index.ts` -- Pelari evaluasi: `src/lib/domain/evalRunner.ts` -- Persistensi status domain: `src/lib/db/domainState.ts` — SQLite CRUD untuk rantai cadangan, anggaran, riwayat biaya, status penguncian, pemutus sirkuit +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Modul penyedia OAuth (12 file individual di bawah `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Indeks registri: `src/lib/oauth/providers/index.ts` -- Penyedia perorangan: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Pembungkus tipis: `src/lib/oauth/providers.ts` — mengekspor ulang dari masing-masing modul +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Lapisan Persistensi +## 3) Persistence Layer -DB negara bagian utama: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- file: `${DATA_DIR}/db.json` (atau `$XDG_CONFIG_HOME/omniroute/db.json` bila disetel, jika tidak `~/.omniroute/db.json`) -- entitas: penyediaConnections, penyediaNodes, modelAliases, kombo, apiKeys, pengaturan, harga, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -DB Penggunaan: +Usage persistence: -- `src/lib/usageDb.ts` -- file: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- mengikuti kebijakan direktori dasar yang sama dengan `localDb` (`DATA_DIR`, lalu `XDG_CONFIG_HOME/omniroute` bila disetel) -- didekomposisi menjadi sub-modul terfokus: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -DB Status Domain (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — Operasi CRUD untuk status domain -- Tabel (dibuat di `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Pola cache write-through: Peta dalam memori bersifat otoritatif saat runtime; mutasi ditulis secara sinkron ke SQLite; keadaan dipulihkan dari DB pada start dingin +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Auth + Permukaan Keamanan +## 4) Auth + Security Surfaces -- Otentikasi cookie dasbor: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Pembuatan/verifikasi kunci API: `src/shared/utils/apiKey.ts` -- Rahasia penyedia tetap ada di `providerConnections` entri -- Dukungan proxy keluar melalui `open-sse/utils/proxyFetch.ts` (env vars) dan `open-sse/utils/networkProxy.ts` (dapat dikonfigurasi per penyedia atau global) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Sinkronisasi Cloud +## 5) Cloud Sync -- Penjadwal init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Tugas berkala: `src/shared/services/cloudSyncScheduler.ts` -- Rute kontrol: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Siklus Hidup Permintaan (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Kombo + Alur Penggantian Akun +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Keputusan cadangan didorong oleh `open-sse/services/accountFallback.ts` menggunakan kode status dan heuristik pesan kesalahan. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Siklus Hidup Orientasi OAuth dan Penyegaran Token +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Penyegaran selama lalu lintas langsung dijalankan di dalam `open-sse/handlers/chatCore.ts` melalui pelaksana `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Siklus Hidup Cloud Sync (Aktifkan / Sinkronisasi / Nonaktifkan) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Sinkronisasi berkala dipicu oleh `CloudSyncScheduler` saat cloud diaktifkan. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Model Data dan Peta Penyimpanan +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -File penyimpanan fisik: +Physical storage files: -- status utama: `${DATA_DIR}/db.json` (atau `$XDG_CONFIG_HOME/omniroute/db.json` jika disetel, jika tidak `~/.omniroute/db.json`) -- statistik penggunaan: `${DATA_DIR}/usage.json` -- baris log permintaan: `${DATA_DIR}/log.txt` -- sesi debug penerjemah/permintaan opsional: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topologi Penerapan +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Pemetaan Modul (Kritis Keputusan) +## Module Mapping (Decision-Critical) -### Rute dan Modul API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API kompatibilitas -- `src/app/api/v1/providers/[provider]/*`: rute khusus per penyedia (obrolan, penyematan, gambar) -- `src/app/api/providers*` : penyedia CRUD, validasi, pengujian -- `src/app/api/provider-nodes*`: manajemen node khusus yang kompatibel -- `src/app/api/provider-models`: manajemen model khusus (CRUD) -- `src/app/api/models/catalog`: API katalog model lengkap (semua jenis dikelompokkan berdasarkan penyedia) -- `src/app/api/oauth/*`: OAuth/kode perangkat mengalir -- `src/app/api/keys*`: siklus hidup kunci API lokal -- `src/app/api/models/alias`: manajemen alias -- `src/app/api/combos*`: manajemen kombo cadangan -- `src/app/api/pricing`: penggantian harga untuk penghitungan biaya -- `src/app/api/settings/proxy`: konfigurasi proksi (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: uji konektivitas proxy keluar (POST) -- `src/app/api/usage/*`: API penggunaan dan log -- `src/app/api/sync/*` + `src/app/api/cloud/*`: sinkronisasi cloud dan pembantu yang menghadap cloud -- `src/app/api/cli-tools/*`: penulis/pemeriksa konfigurasi CLI lokal -- `src/app/api/settings/ip-filter`: Daftar IP yang diizinkan/daftar blokir (GET/PUT) -- `src/app/api/settings/thinking-budget`: memikirkan konfigurasi anggaran token (GET/PUT) -- `src/app/api/settings/system-prompt`: perintah sistem global (GET/PUT) -- `src/app/api/sessions`: daftar sesi aktif (GET) -- `src/app/api/rate-limits`: status batas tarif per akun (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Perutean dan Inti Eksekusi +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: penguraian permintaan, penanganan kombo, putaran pemilihan akun -- `open-sse/handlers/chatCore.ts`: terjemahan, pengiriman eksekutor, penanganan coba lagi/segarkan, pengaturan streaming -- `open-sse/executors/*`: perilaku format dan jaringan khusus penyedia +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Registri Terjemahan dan Pengonversi Format +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: registrasi dan orkestrasi penerjemah -- Permintaan penerjemah: `open-sse/translator/request/*` -- Penerjemah tanggapan: `open-sse/translator/response/*` -- Konstanta format: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Ketekunan +### Persistence -- `src/lib/localDb.ts`: konfigurasi/status persisten -- `src/lib/usageDb.ts`: riwayat penggunaan dan log permintaan bergulir +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Cakupan Pelaksana Penyedia (Pola Strategi) +## Provider Executor Coverage (Strategy Pattern) -Setiap penyedia memiliki pelaksana khusus yang memperluas `BaseExecutor` (di `open-sse/executors/base.ts`), yang menyediakan pembuatan URL, konstruksi header, percobaan ulang dengan backoff eksponensial, kait penyegaran kredensial, dan metode orkestrasi `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Pelaksana | Penyedia | Penanganan Khusus | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Kebingungan, Bersama, Kembang Api, Cerebras, Cohere, NVIDIA | Konfigurasi URL/tajuk dinamis per penyedia | -| `AntigravityExecutor` | Google Antigravitasi | ID proyek/sesi khusus, Coba Lagi-Setelah penguraian | -| `CodexExecutor` | Kodeks OpenAI | Menyuntikkan instruksi sistem, memaksakan upaya penalaran | -| `CursorExecutor` | IDE Kursor | Protokol ConnectRPC, pengkodean Protobuf, penandatanganan permintaan melalui checksum | -| `GithubExecutor` | Kopilot GitHub | Penyegaran token kopilot, header yang meniru VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Format biner AWS EventStream → konversi SSE | -| `GeminiCLIExecutor` | CLI Gemini | Siklus penyegaran token Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Semua penyedia lain (termasuk node khusus yang kompatibel) menggunakan `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matriks Kompatibilitas Penyedia +## Provider Compatibility Matrix -| Penyedia | Format | Otentikasi | Aliran | Non-Aliran | Penyegaran Token | API Penggunaan | -| ---------------- | ---------------- | --------------------- | ----------------- | ---------- | ---------------- | --------------------- | -| Claude | claude | Kunci API / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin saja | -| kembar | gemilang | Kunci API / OAuth | ✅ | ✅ | ✅ | ⚠️ Konsol Cloud | -| CLI Gemini | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Konsol Cloud | -| Antigravitasi | antigravitasi | OAuth | ✅ | ✅ | ✅ | ✅ API kuota penuh | -| OpenAI | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Kodeks | openai-responses | OAuth | ✅ dipaksa | ❌ | ✅ | ✅ Batas tarif | -| Kopilot GitHub | buka | OAuth + Token Kopilot | ✅ | ✅ | ✅ | ✅ Cuplikan kuota | -| Kursor | kursor | Checksum khusus | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiri | AWSSSO OIDC | ✅ (Aliran Acara) | ❌ | ✅ | ✅ Batasan penggunaan | -| Qwen | buka | OAuth | ✅ | ✅ | ✅ | ⚠️ Sesuai permintaan | -| iFlow | buka | OAuth (Dasar) | ✅ | ✅ | ✅ | ⚠️ Sesuai permintaan | -| BukaRouter | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Pencarian Dalam | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Bagus | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Mistral | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Kebingungan | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Bersama AI | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| AI kembang api | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Otak | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| menyatu | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Format Cakupan Terjemahan +## Format Translation Coverage -Format sumber yang terdeteksi meliputi: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Format sasaran meliputi: +Target formats include: -- Obrolan/Respon OpenAI +- OpenAI chat/Responses - Claude -- Amplop Gemini/Gemini-CLI/Antigravitasi +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Kursor +- Cursor -Penerjemahan menggunakan **OpenAI sebagai format hub** — semua konversi melalui OpenAI sebagai perantara: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Terjemahan dipilih secara dinamis berdasarkan bentuk muatan sumber dan format target penyedia. +Translations are selected dynamically based on source payload shape and provider target format. -Lapisan pemrosesan tambahan dalam alur terjemahan: +Additional processing layers in the translation pipeline: -- **Sanitasi respons** — Menghapus kolom non-standar dari respons format OpenAI (streaming dan non-streaming) untuk memastikan kepatuhan SDK yang ketat -- **Normalisasi peran** — Mengonversi `developer` → `system` untuk target non-OpenAI; menggabungkan `system` → `user` untuk model yang menolak peran sistem (GLM, ERNIE) -- **Pikirkan ekstraksi tag** — Mengurai `...` blok dari konten ke dalam bidang `reasoning_content` -- **Output terstruktur** — Mengonversi OpenAI `response_format.json_schema` menjadi `responseMimeType` + `responseSchema` Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Titik Akhir API yang Didukung +## Supported API Endpoints -| Titik akhir | Format | Penangan | -| -------------------------------------------------- | ------------------- | ------------------------------------------------------- | -| `POST /v1/chat/completions` | Obrolan OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Pesan Claude | Penangan yang sama (terdeteksi otomatis) | -| `POST /v1/responses` | Tanggapan OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Penyematan OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Daftar model | Rute API | -| `POST /v1/images/generations` | Gambar OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Daftar model | Rute API | -| `POST /v1/providers/{provider}/chat/completions` | Obrolan OpenAI | Per penyedia khusus dengan validasi model | -| `POST /v1/providers/{provider}/embeddings` | Penyematan OpenAI | Per penyedia khusus dengan validasi model | -| `POST /v1/providers/{provider}/images/generations` | Gambar OpenAI | Per penyedia khusus dengan validasi model | -| `POST /v1/messages/count_tokens` | Jumlah Token Claude | Rute API | -| `GET /v1/models` | Daftar Model OpenAI | Rute API (obrolan + penyematan + gambar + model khusus) | -| `GET /api/models/catalog` | Katalog | Semua model dikelompokkan berdasarkan penyedia + tipe | -| `POST /v1beta/models/*:streamGenerateContent` | Gemini asli | Rute API | -| `GET/PUT/DELETE /api/settings/proxy` | Konfigurasi Proksi | Konfigurasi proksi jaringan | -| `POST /api/settings/proxy/test` | Konektivitas Proksi | Titik akhir pengujian kesehatan/konektivitas proxy | -| `GET/POST/DELETE /api/provider-models` | Model Khusus | Manajemen model khusus per penyedia | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Pengendali Pintas +## Bypass Handler -Penangan bypass (`open-sse/utils/bypassHandler.ts`) mencegat permintaan "sekali pakai" yang diketahui dari Claude CLI — ping pemanasan, ekstraksi judul, dan jumlah token — dan mengembalikan **respons palsu** tanpa menggunakan token penyedia upstream. Ini dipicu hanya ketika `User-Agent` berisi `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Minta Saluran Logger +## Request Logger Pipeline -Logger permintaan (`open-sse/utils/requestLogger.ts`) menyediakan pipeline debug logging 7 tahap, dinonaktifkan secara default, diaktifkan melalui `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -File ditulis ke `/logs//` untuk setiap sesi permintaan. +Files are written to `/logs//` for each request session. -## Mode Kegagalan dan Ketahanan +## Failure Modes and Resilience -## 1) Ketersediaan Akun/Penyedia +## 1) Account/Provider Availability -- cooldown akun penyedia pada kesalahan sementara/rate/auth -- penggantian akun sebelum permintaan gagal -- penggantian model kombo ketika jalur model/penyedia saat ini habis +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Kedaluwarsa Token +## 2) Token Expiry -- pra-periksa dan segarkan dengan coba lagi untuk penyedia yang dapat disegarkan -- 401/403 percobaan ulang setelah upaya penyegaran di jalur inti +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Keamanan Aliran +## 3) Stream Safety -- pengontrol aliran yang sadar akan pemutusan hubungan -- aliran terjemahan dengan flush akhir aliran dan penanganan `[DONE]` -- penggantian estimasi penggunaan ketika metadata penggunaan penyedia tidak ada +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Degradasi Sinkronisasi Cloud +## 4) Cloud Sync Degradation -- kesalahan sinkronisasi muncul tetapi runtime lokal terus berlanjut -- penjadwal memiliki logika yang mampu mencoba ulang, namun eksekusi berkala saat ini memanggil sinkronisasi upaya tunggal secara default +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integritas Data +## 5) Data Integrity -- Migrasi/perbaikan bentuk DB untuk kunci yang hilang -- perlindungan reset JSON yang rusak untuk localDb dan usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Observabilitas dan Sinyal Operasional +## Observability and Operational Signals -Sumber visibilitas waktu proses: +Runtime visibility sources: -- log konsol dari `src/sse/utils/logger.ts` -- agregat penggunaan per permintaan di `usage.json` -- status permintaan tekstual masuk `log.txt` -- log permintaan/terjemahan dalam opsional di bawah `logs/` ketika `ENABLE_REQUEST_LOGS=true` -- titik akhir penggunaan dasbor (`/api/usage/*`) untuk konsumsi UI +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Batasan yang Sensitif terhadap Keamanan +## Security-Sensitive Boundaries -- Rahasia JWT (`JWT_SECRET`) mengamankan verifikasi/penandatanganan cookie sesi dasbor -- Penggantian kata sandi awal (`INITIAL_PASSWORD`, default `123456`) harus diganti dalam penerapan nyata -- Rahasia HMAC kunci API (`API_KEY_SECRET`) mengamankan format kunci API lokal yang dihasilkan -- Rahasia penyedia (kunci/token API) disimpan di DB lokal dan harus dilindungi di tingkat sistem file -- Titik akhir sinkronisasi cloud mengandalkan autentikasi kunci API + semantik id mesin +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Matriks Lingkungan dan Runtime +## Environment and Runtime Matrix -Variabel lingkungan yang aktif digunakan oleh kode: +Environment variables actively used by code: -- Aplikasi/autentikasi: `JWT_SECRET`, `INITIAL_PASSWORD` -- Penyimpanan: `DATA_DIR` -- Perilaku node yang kompatibel: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Penggantian basis penyimpanan opsional (Linux/macOS ketika `DATA_DIR` tidak disetel): `XDG_CONFIG_HOME` -- Pencirian keamanan: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Pencatatan: `ENABLE_REQUEST_LOGS` -- URL sinkronisasi/cloud: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Proksi keluar: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` dan varian huruf kecil -- Bendera fitur SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Pembantu platform/runtime (bukan konfigurasi khusus aplikasi): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Catatan Arsitektur yang Dikenal +## Known Architectural Notes -1. `usageDb` dan `localDb` sekarang berbagi kebijakan direktori dasar yang sama (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) dengan migrasi file lama. -2. `/api/v1/route.ts` mengembalikan daftar model statis dan bukan sumber model utama yang digunakan oleh `/v1/models`. -3. Pencatat permintaan menulis header/isi lengkap saat diaktifkan; memperlakukan direktori log sebagai sensitif. -4. Perilaku cloud bergantung pada `NEXT_PUBLIC_BASE_URL` yang benar dan jangkauan titik akhir cloud. -5. Direktori `open-sse/` diterbitkan sebagai `@omniroute/open-sse` **paket ruang kerja npm**. Kode sumber mengimpornya melalui `@omniroute/open-sse/...` (diselesaikan oleh Next.js `transpilePackages`). Jalur file dalam dokumen ini masih menggunakan nama direktori `open-sse/` untuk konsistensi. -6. Bagan di dasbor menggunakan **Recharts** (berbasis SVG) untuk visualisasi analitik interaktif yang mudah diakses (diagram batang penggunaan model, tabel perincian penyedia dengan tingkat keberhasilan). -7. Tes E2E menggunakan **Playwright** (`tests/e2e/`), dijalankan melalui `npm run test:e2e`. Pengujian unit menggunakan **Node.js test runner** (`tests/unit/`), dijalankan melalui `npm run test:plan3`. Kode sumber di bawah `src/` adalah **TypeScript** (`.ts`/`.tsx`); ruang kerja `open-sse/` tetap JavaScript (`.js`). -8. Halaman pengaturan disusun dalam 5 tab: Keamanan, Perutean (6 strategi global: isi dulu, round-robin, p2c, acak, jarang digunakan, optimal biaya), Ketahanan (batas kecepatan yang dapat diedit, pemutus sirkuit, kebijakan), AI (anggaran berpikir, perintah sistem, cache cepat), Lanjutan (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Daftar Periksa Verifikasi Operasional +## Operational Verification Checklist -- Bangun dari sumber: `npm run build` -- Bangun gambar Docker: `docker build -t omniroute .` -- Mulai layanan dan verifikasi: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- URL dasar target CLI harus `http://:20128/v1` ketika `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/id/CODEBASE_DOCUMENTATION.md b/docs/i18n/id/CODEBASE_DOCUMENTATION.md index 2fe7782036..303880c198 100644 --- a/docs/i18n/id/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/id/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Dokumentasi Basis Kode +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Panduan komprehensif dan mudah bagi pemula untuk router proxy AI multi-penyedia **omniroute**. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Apa itu omniroute? +## 1. What Is omniroute? -omniroute adalah **router proxy** yang berada di antara klien AI (Claude CLI, Codex, Cursor IDE, dll.) dan penyedia AI (Anthropic, Google, OpenAI, AWS, GitHub, dll.). Ini memecahkan satu masalah besar: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Klien AI yang berbeda menggunakan "bahasa" (format API) yang berbeda, dan penyedia AI yang berbeda juga mengharapkan "bahasa" yang berbeda.** omniroute menerjemahkan bahasa tersebut secara otomatis. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Anggap saja seperti penerjemah universal di Perserikatan Bangsa-Bangsa — setiap delegasi dapat berbicara dalam bahasa apa pun, dan penerjemah tersebut mengonversikannya untuk delegasi lainnya. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Ikhtisar Arsitektur +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Prinsip Inti: Penerjemahan Hub-and-Spoke +### Core Principle: Hub-and-Spoke Translation -Semua terjemahan format melewati **format OpenAI sebagai hub**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Artinya, Anda hanya memerlukan **N penerjemah** (satu per format) dan bukan **N²** (setiap pasangan). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Struktur Proyek +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Perincian Modul demi Modul +## 4. Module-by-Module Breakdown -### 4.1 Konfigurasi (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**Satu-satunya sumber kebenaran** untuk semua konfigurasi penyedia. +The **single source of truth** for all provider configuration. -| Berkas | Tujuan | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | Objek `PROVIDERS` dengan URL dasar, kredensial OAuth (default), header, dan perintah sistem default untuk setiap penyedia. Juga mendefinisikan `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, dan `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Memuat kredensial eksternal dari `data/provider-credentials.json` dan menggabungkannya melalui default hardcode di `PROVIDERS`. Menjaga rahasia di luar kendali sumber sambil menjaga kompatibilitas ke belakang. | -| `providerModels.ts` | Registri model pusat: alias penyedia peta → ID model. Fungsi seperti `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Instruksi sistem dimasukkan ke dalam permintaan Codex (batasan pengeditan, aturan sandbox, kebijakan persetujuan). | -| `defaultThinkingSignature.ts` | Tanda tangan "berpikir" default untuk model Claude dan Gemini. | -| `ollamaModels.ts` | Definisi skema untuk model Ollama lokal (nama, ukuran, keluarga, kuantisasi). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Alur Pemuatan Kredensial +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Pelaksana (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Pelaksana merangkum **logika khusus penyedia** menggunakan **Pola Strategi**. Setiap pelaksana mengganti metode dasar sesuai kebutuhan. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Pelaksana | Penyedia | Spesialisasi Utama | -| ---------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Basis abstrak: Pembuatan URL, header, logika coba lagi, penyegaran kredensial | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Penyegaran token OAuth generik untuk penyedia standar | -| `antigravity.ts` | Kode Google Cloud | Pembuatan ID proyek/sesi, penggantian multi-URL, penguraian coba ulang khusus dari pesan kesalahan ("reset setelah 2h7m23s") | -| `cursor.ts` | IDE Kursor | **Paling rumit**: autentikasi checksum SHA-256, pengkodean permintaan Protobuf, biner EventStream → penguraian respons SSE | -| `codex.ts` | Kodeks OpenAI | Menyuntikkan instruksi sistem, mengelola tingkat pemikiran, menghapus parameter yang tidak didukung | -| `gemini-cli.ts` | CLI Google Gemini | Pembuatan URL khusus (`streamGenerateContent`), penyegaran token Google OAuth | -| `github.ts` | Kopilot GitHub | Sistem token ganda (GitHub OAuth + token Copilot), header VSCode meniru | -| `kiro.ts` | AWS CodeWhisperer | Penguraian biner AWS EventStream, bingkai peristiwa AMZN, estimasi token | -| `index.ts` | — | Pabrik: nama penyedia peta → kelas pelaksana, dengan fallback default | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Penangan (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**Lapisan orkestrasi** — mengoordinasikan terjemahan, eksekusi, streaming, dan penanganan kesalahan. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Berkas | Tujuan | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `chatCore.ts` | **Orkestra pusat** (~600 baris). Menangani siklus hidup permintaan secara lengkap: deteksi format → terjemahan → pengiriman pelaksana → respons streaming/non-streaming → penyegaran token → penanganan kesalahan → pencatatan penggunaan. | -| `responsesHandler.ts` | Adaptor untuk API Respons OpenAI: mengonversi format Respons → Penyelesaian Obrolan → mengirim ke `chatCore` → mengonversi SSE kembali ke format Respons. | -| `embeddings.ts` | Penangan generasi penyematan: menyelesaikan model penyematan → penyedia, mengirimkan ke API penyedia, mengembalikan respons penyematan yang kompatibel dengan OpenAI. Mendukung 6+ penyedia. | -| `imageGeneration.ts` | Pengendali pembuatan gambar: menyelesaikan model gambar → penyedia, mendukung mode yang kompatibel dengan OpenAI, gambar Gemini (Antigravity), dan fallback (Nebius). Mengembalikan gambar base64 atau URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Siklus Hidup Permintaan (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Layanan (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Logika bisnis yang mendukung penangan dan pelaksana. +Business logic that supports the handlers and executors. -| Berkas | Tujuan | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Deteksi format** (`detectFormat`): menganalisis struktur isi permintaan untuk mengidentifikasi format Claude/OpenAI/Gemini/Antigravity/Responses (termasuk heuristik `max_tokens` untuk Claude). Juga: pembuatan URL, pembuatan header, normalisasi konfigurasi pemikiran. Mendukung penyedia dinamis `openai-compatible-*` dan `anthropic-compatible-*`. | -| `model.ts` | Penguraian string model (`claude/model-name` → `{provider: "claude", model: "model-name"}`), resolusi alias dengan deteksi tabrakan, sanitasi input (menolak traversal jalur/karakter kontrol), dan resolusi info model dengan dukungan pengambil alias asinkron. | -| `accountFallback.ts` | Penanganan batas kecepatan: backoff eksponensial (1 dtk → 2 dtk → 4 dtk → maks 2 menit), manajemen cooldown akun, klasifikasi kesalahan (kesalahan mana yang memicu fallback vs. tidak). | -| `tokenRefresh.ts` | Penyegaran token OAuth untuk **setiap penyedia**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Termasuk cache deduplikasi janji dalam penerbangan dan coba lagi dengan backoff eksponensial. | -| `combo.ts` | **Model kombo**: rangkaian model cadangan. Jika model A gagal dengan kesalahan yang memenuhi syarat fallback, coba model B, lalu C, dan seterusnya. Mengembalikan kode status upstream yang sebenarnya. | -| `usage.ts` | Mengambil data kuota/penggunaan dari API penyedia (kuota GitHub Copilot, kuota model Antigravity, batas kecepatan Codex, perincian penggunaan Kiro, pengaturan Claude). | -| `accountSelector.ts` | Pemilihan akun cerdas dengan algoritma penilaian: mempertimbangkan prioritas, status kesehatan, posisi round-robin, dan status cooldown untuk memilih akun optimal untuk setiap permintaan. | -| `contextManager.ts` | Manajemen siklus hidup konteks permintaan: membuat dan melacak objek konteks per permintaan dengan metadata (ID permintaan, stempel waktu, info penyedia) untuk debugging dan logging. | -| `ipFilter.ts` | Kontrol akses berbasis IP: mendukung mode daftar yang diizinkan dan daftar blokir. Memvalidasi IP klien terhadap aturan yang dikonfigurasi sebelum memproses permintaan API. | -| `sessionManager.ts` | Pelacakan sesi dengan sidik jari klien: melacak sesi aktif menggunakan pengidentifikasi klien yang di-hash, memantau jumlah permintaan, dan menyediakan metrik sesi. | -| `signatureCache.ts` | Permintaan cache deduplikasi berbasis tanda tangan: mencegah permintaan duplikat dengan menyimpan tanda tangan permintaan terbaru dalam cache dan mengembalikan respons cache untuk permintaan serupa dalam jangka waktu tertentu. | -| `systemPrompt.ts` | Injeksi perintah sistem global: menambahkan atau menambahkan perintah sistem yang dapat dikonfigurasi ke semua permintaan, dengan penanganan kompatibilitas per penyedia. | -| `thinkingBudget.ts` | Manajemen anggaran token penalaran: mendukung mode passthrough, otomatis (konfigurasi pemikiran strip), kustom (anggaran tetap), dan adaptif (skala kompleksitas) untuk mengendalikan token pemikiran/penalaran. | -| `wildcardRouter.ts` | Perutean pola model wildcard: menyelesaikan pola wildcard (misalnya, `*/claude-*`) ke pasangan penyedia/model tertentu berdasarkan ketersediaan dan prioritas. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Deduplikasi Penyegaran Token +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Mesin Status Penggantian Akun +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Rantai Model Kombo +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Penerjemah (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**mesin terjemahan format** menggunakan sistem plugin pendaftaran mandiri. +The **format translation engine** using a self-registering plugin system. -#### Arsitektur +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Direktori | File | Deskripsi | -| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `request/` | 8 penerjemah | Konversi badan permintaan antar format. Setiap file didaftarkan sendiri melalui `register(from, to, fn)` saat diimpor. | -| `response/` | 7 penerjemah | Konversikan potongan respons streaming antar format. Menangani jenis acara SSE, blok pemikiran, panggilan alat. | -| `helpers/` | 6 pembantu | Utilitas bersama: `claudeHelper` (ekstraksi prompt sistem, konfigurasi pemikiran), `geminiHelper` (pemetaan bagian/konten), `openaiHelper` (pemfilteran format), `toolCallHelper` (pembuatan ID, injeksi respons hilang), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Mesin penerjemah: `translateRequest()`, `translateResponse()`, manajemen negara, registri. | -| `formats.ts` | — | Konstanta format: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Desain Kunci: Plugin Pendaftaran Mandiri +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Kegunaan (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Berkas | Tujuan | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Pembuatan respons kesalahan (format yang kompatibel dengan OpenAI), penguraian kesalahan hulu, ekstraksi waktu percobaan ulang Antigravitasi dari pesan kesalahan, streaming kesalahan SSE. | -| `stream.ts` | **SSE Transform Stream** — saluran streaming inti. Dua mode: `TRANSLATE` (terjemahan format penuh) dan `PASSTHROUGH` (menormalkan + mengekstrak penggunaan). Menangani buffering potongan, estimasi penggunaan, pelacakan panjang konten. Instance encoder/decoder per-aliran menghindari status bersama. | -| `streamHelpers.ts` | Utilitas SSE tingkat rendah: `parseSSELine` (toleran spasi), `hasValuableContent` (memfilter potongan kosong untuk OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialisasi SSE yang mendukung format dengan pembersihan `perf_metrics`). | -| `usageTracking.ts` | Ekstraksi penggunaan token dari format apa pun (Claude/OpenAI/Gemini/Responses), estimasi dengan rasio karakter per token alat/pesan terpisah, penambahan buffer (margin keamanan token 2000), pemfilteran bidang khusus format, logging konsol dengan warna ANSI. | -| `requestLogger.ts` | Pencatatan permintaan berbasis file (ikut serta melalui `ENABLE_REQUEST_LOGS=true`). Membuat folder sesi dengan file bernomor: `1_req_client.json` → `7_res_client.txt`. Semua I/O bersifat asinkron (api-dan-lupakan). Menutupi header sensitif. | -| `bypassHandler.ts` | Mencegat pola tertentu dari Claude CLI (ekstraksi judul, pemanasan, penghitungan) dan mengembalikan respons palsu tanpa menghubungi penyedia mana pun. Mendukung streaming dan non-streaming. Sengaja dibatasi pada scope Claude CLI. | -| `networkProxy.ts` | Menyelesaikan URL proksi keluar untuk penyedia tertentu dengan prioritas: konfigurasi khusus penyedia → konfigurasi global → variabel lingkungan (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Mendukung pengecualian `NO_PROXY`. Konfigurasi cache selama 30 detik. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Saluran Pipa Streaming SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Struktur Sesi Pencatat Permintaan +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Lapisan Aplikasi (`src/`) +### 4.7 Application Layer (`src/`) -| Direktori | Tujuan | -| ------------- | ------------------------------------------------------------------------------------ | -| `src/app/` | UI web, rute API, middleware Express, penangan panggilan balik OAuth | -| `src/lib/` | Akses basis data (`localDb.ts`, `usageDb.ts`), autentikasi, dibagikan | -| `src/mitm/` | Utilitas proxy man-in-the-middle untuk mencegat lalu lintas penyedia | -| `src/models/` | Definisi model basis data | -| `src/shared/` | Pembungkus di sekitar fungsi open-sse (penyedia, aliran, kesalahan, dll.) | -| `src/sse/` | Penangan titik akhir SSE yang menghubungkan perpustakaan sse terbuka ke rute Ekspres | -| `src/store/` | Manajemen status aplikasi | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Rute API Penting +#### Notable API Routes -| Rute | Metode | Tujuan | -| --------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | DAPATKAN/POSTING/HAPUS | CRUD untuk model khusus per penyedia | -| `/api/models/catalog` | DAPATKAN | Katalog gabungan semua model (obrolan, penyematan, gambar, khusus) dikelompokkan berdasarkan penyedia | -| `/api/settings/proxy` | DAPATKAN/MASUKKAN/HAPUS | Konfigurasi proksi keluar hierarki (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POSTING | Memvalidasi konektivitas proxy dan mengembalikan IP/latensi publik | -| `/v1/providers/[provider]/chat/completions` | POSTING | Penyelesaian obrolan khusus per penyedia dengan validasi model | -| `/v1/providers/[provider]/embeddings` | POSTING | Penyematan khusus per penyedia dengan validasi model | -| `/v1/providers/[provider]/images/generations` | POSTING | Pembuatan gambar khusus per penyedia dengan validasi model | -| `/api/settings/ip-filter` | DAPATKAN/MASUKKAN | Manajemen daftar IP yang diizinkan/daftar blokir | -| `/api/settings/thinking-budget` | DAPATKAN/MASUKKAN | Penalaran konfigurasi anggaran token (passthrough/auto/custom/adaptive) | -| `/api/settings/system-prompt` | DAPATKAN/MASUKKAN | Injeksi prompt sistem global untuk semua permintaan | -| `/api/sessions` | DAPATKAN | Pelacakan dan metrik sesi aktif | -| `/api/rate-limits` | DAPATKAN | Status batas tarif per akun | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Pola Desain Utama +## 5. Key Design Patterns -### 5.1 Terjemahan Hub-and-Spoke +### 5.1 Hub-and-Spoke Translation -Semua format diterjemahkan melalui **format OpenAI sebagai hub**. Menambahkan penyedia baru hanya memerlukan penulisan **satu pasang** penerjemah (ke/dari OpenAI), bukan N pasang. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Pola Strategi Pelaksana +### 5.2 Executor Strategy Pattern -Setiap penyedia memiliki kelas eksekutor khusus yang diwarisi dari `BaseExecutor`. Pabrik di `executors/index.ts` memilih yang tepat saat runtime. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Sistem Plugin Pendaftaran Mandiri +### 5.3 Self-Registering Plugin System -Modul penerjemah mendaftarkan dirinya saat diimpor melalui `register()`. Menambahkan penerjemah baru hanyalah membuat file dan mengimpornya. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Penggantian Akun dengan Backoff Eksponensial +### 5.4 Account Fallback with Exponential Backoff -Ketika penyedia mengembalikan 429/401/500, sistem dapat beralih ke akun berikutnya, menerapkan cooldown eksponensial (1 dtk → 2 dtk → 4 dtk → maksimal 2 menit). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Rantai Model Kombo +### 5.5 Combo Model Chains -Sebuah "kombo" mengelompokkan beberapa string `provider/model`. Jika yang pertama gagal, kembali ke yang berikutnya secara otomatis. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Terjemahan Streaming Stateful +### 5.6 Stateful Streaming Translation -Terjemahan respons mempertahankan status di seluruh potongan SSE (pelacakan blok pemikiran, akumulasi panggilan alat, pengindeksan blok konten) melalui mekanisme `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Buffer Keamanan Penggunaan +### 5.7 Usage Safety Buffer -Buffer 2000 token ditambahkan ke penggunaan yang dilaporkan untuk mencegah klien mencapai batas jendela konteks karena overhead dari perintah sistem dan terjemahan format. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Format yang Didukung +## 6. Supported Formats -| Format | Arah | Pengenal | -| --------------------------- | ---------------- | ------------------ | -| Penyelesaian Obrolan OpenAI | sumber + sasaran | `openai` | -| API Respons OpenAI | sumber + sasaran | `openai-responses` | -| Claude Antropik | sumber + sasaran | `claude` | -| Google Gemini | sumber + sasaran | `gemini` | -| CLI Google Gemini | hanya sasaran | `gemini-cli` | -| Antigravitasi | sumber + sasaran | `antigravity` | -| AWSKiro | hanya sasaran | `kiro` | -| Kursor | hanya sasaran | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Penyedia yang Didukung +## 7. Supported Providers -| Penyedia | Metode Otentikasi | Pelaksana | Catatan Penting | -| ------------------------ | ------------------------ | ------------- | ---------------------------------------------------------- | -| Claude Antropik | Kunci API atau OAuth | Bawaan | Menggunakan tajuk `x-api-key` | -| Google Gemini | Kunci API atau OAuth | Bawaan | Menggunakan tajuk `x-goog-api-key` | -| CLI Google Gemini | OAuth | Gemini CLI | Menggunakan titik akhir `streamGenerateContent` | -| Antigravitasi | OAuth | Antigravitasi | Penggantian multi-URL, penguraian coba ulang khusus | -| OpenAI | Kunci API | Bawaan | Autentikasi Pembawa Standar | -| Kodeks | OAuth | Kodeks | Menyuntikkan instruksi sistem, mengelola pemikiran | -| Kopilot GitHub | OAuth + Token Kopilot | Github | Token ganda, header VSCode meniru | -| Kiro (AWS) | AWS SSO OIDC atau Sosial | Kiro | Penguraian Biner EventStream | -| IDE Kursor | Otentikasi checksum | Kursor | Pengkodean protobuf, checksum SHA-256 | -| Qwen | OAuth | Bawaan | Otentikasi standar | -| iFlow | OAuth (Dasar + Pembawa) | Bawaan | Header autentikasi ganda | -| BukaRouter | Kunci API | Bawaan | Autentikasi Pembawa Standar | -| GLM, Kimi, MiniMax | Kunci API | Bawaan | Kompatibel dengan Claude, gunakan `x-api-key` | -| `openai-compatible-*` | Kunci API | Bawaan | Dinamis: semua titik akhir yang kompatibel dengan OpenAI | -| `anthropic-compatible-*` | Kunci API | Bawaan | Dinamis: titik akhir apa pun yang kompatibel dengan Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Ringkasan Aliran Data +## 8. Data Flow Summary -### Permintaan Streaming +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Permintaan Non-Streaming +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Aliran Bypass (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/id/FEATURES.md b/docs/i18n/id/FEATURES.md index f348e734cc..82cc73b67b 100644 --- a/docs/i18n/id/FEATURES.md +++ b/docs/i18n/id/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Galeri Fitur Dasbor +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Panduan visual untuk setiap bagian dasbor OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Penyedia +## 🔌 Providers -Kelola koneksi penyedia AI: Penyedia OAuth (Claude Code, Codex, Gemini CLI), penyedia kunci API (Groq, DeepSeek, OpenRouter), dan penyedia gratis (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Kombo +## 🎨 Combos -Buat kombo perutean model dengan 6 strategi: pengisian pertama, round-robin, pilihan ganda, acak, paling jarang digunakan, dan hemat biaya. Setiap kombo merangkai beberapa model dengan fallback otomatis. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Analisis +## 📊 Analytics -Analisis penggunaan yang komprehensif dengan konsumsi token, perkiraan biaya, peta panas aktivitas, grafik distribusi mingguan, dan perincian per penyedia. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Kesehatan Sistem +## 🏥 System Health -Pemantauan waktu nyata: waktu aktif, memori, versi, persentil latensi (p50/p95/p99), statistik cache, dan status pemutus sirkuit penyedia. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Taman Bermain Penerjemah +## 🔧 Translator Playground -Empat mode untuk men-debug terjemahan API: **Playground** (konverter format), **Chat Tester** (permintaan langsung), **Test Bench** (pengujian batch), dan **Live Monitor** (streaming real-time). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Pengaturan +## 🎮 Model Playground _(v2.0.9+)_ -Pengaturan umum, penyimpanan sistem, manajemen cadangan (database ekspor/impor), tampilan (mode gelap/terang), keamanan (termasuk perlindungan titik akhir API dan pemblokiran penyedia khusus), perutean, ketahanan, dan konfigurasi lanjutan. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Alat CLI +## 🔧 CLI Tools -Konfigurasi sekali klik untuk alat pengkodean AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, dan Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Minta Log +## 🤖 CLI Agents _(v2.0.11+)_ -Pencatatan permintaan secara real-time dengan pemfilteran berdasarkan penyedia, model, akun, dan kunci API. Menampilkan kode status, penggunaan token, latensi, dan detail respons. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Titik Akhir API +## 🌐 API Endpoint -Titik akhir API terpadu Anda dengan perincian kemampuan: Penyelesaian Obrolan, Penyematan, Pembuatan Gambar, Pemeringkatan Ulang, Transkripsi Audio, dan kunci API terdaftar. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/id/TROUBLESHOOTING.md b/docs/i18n/id/TROUBLESHOOTING.md index e4cf93cdfb..120092d63c 100644 --- a/docs/i18n/id/TROUBLESHOOTING.md +++ b/docs/i18n/id/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Pemecahan masalah +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Masalah umum dan solusi untuk OmniRoute. +Common problems and solutions for OmniRoute. --- -## Perbaikan Cepat +## Quick Fixes -| Masalah | Solusi | -| ----------------------------------------- | ----------------------------------------------------------------------- | -| Login pertama tidak berfungsi | Centang `INITIAL_PASSWORD` di `.env` (default: `123456`) | -| Dasbor terbuka pada port yang salah | Tetapkan `PORT=20128` dan `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Tidak ada log permintaan di bawah `logs/` | Setel `ENABLE_REQUEST_LOGS=true` | -| EACCES: izin ditolak | Setel `DATA_DIR=/path/to/writable/dir` untuk mengganti `~/.omniroute` | -| Strategi perutean tidak menyimpan | Perbarui ke v1.4.11+ (perbaikan skema Zod untuk persistensi pengaturan) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Masalah Penyedia +## Provider Issues -### "Model bahasa tidak memberikan pesan" +### "Language model did not provide messages" -**Penyebab:** Kuota penyedia habis. +**Cause:** Provider quota exhausted. -**Perbaikan:** +**Fix:** -1. Periksa pelacak kuota dasbor -2. Gunakan kombo dengan tier fallback -3. Beralih ke tingkat yang lebih murah/gratis +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Pembatasan Nilai +### Rate Limiting -**Penyebab:** Kuota berlangganan habis. +**Cause:** Subscription quota exhausted. -**Perbaikan:** +**Fix:** -- Tambahkan cadangan: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Gunakan GLM/MiniMax sebagai cadangan murah +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Token OAuth Kedaluwarsa +### OAuth Token Expired -OmniRoute menyegarkan token secara otomatis. Jika masalah terus berlanjut: +OmniRoute auto-refreshes tokens. If issues persist: -1. Dasbor → Penyedia → Sambungkan kembali -2. Hapus dan tambahkan kembali koneksi penyedia +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Masalah Awan +## Cloud Issues -### Kesalahan Sinkronisasi Cloud +### Cloud Sync Errors -1. Verifikasikan `BASE_URL` poin ke instance Anda yang sedang berjalan (misalnya, `http://localhost:20128`) -2. Verifikasikan `CLOUD_URL` poin ke titik akhir cloud Anda (misalnya, `https://omniroute.dev`) -3. Jaga agar nilai `NEXT_PUBLIC_*` selaras dengan nilai sisi server +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Mengembalikan 500 +### Cloud `stream=false` Returns 500 -**Gejala:** `Unexpected token 'd'...` di titik akhir cloud untuk panggilan non-streaming. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Penyebab:** Upstream mengembalikan payload SSE sementara klien mengharapkan JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Solusi:** Gunakan `stream=true` untuk panggilan langsung cloud. Waktu proses lokal mencakup penggantian SSE→JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud Mengatakan Terhubung tetapi "Kunci API tidak valid" +### Cloud Says Connected but "Invalid API key" -1. Buat kunci baru dari dasbor lokal (`/api/keys`) -2. Jalankan sinkronisasi cloud: Aktifkan Cloud → Sinkronkan Sekarang -3. Kunci lama/tidak tersinkronisasi masih dapat mengembalikan `401` di cloud +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Masalah Docker +## Docker Issues -### Alat CLI Tidak Dipasang +### CLI Tool Shows Not Installed -1. Periksa kolom runtime: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Untuk mode portabel: gunakan target gambar `runner-cli` (CL yang dibundel) -3. Untuk mode pemasangan host: setel `CLI_EXTRA_PATHS` dan pasang direktori host bin sebagai hanya-baca -4. Jika `installed=true` dan `runnable=false`: biner ditemukan tetapi pemeriksaan kesehatan gagal +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Validasi Waktu Proses Cepat +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Masalah Biaya +## Cost Issues -### Biaya Tinggi +### High Costs -1. Periksa statistik penggunaan di Dashboard → Penggunaan -2. Ganti model utama ke GLM/MiniMax -3. Gunakan tingkat gratis (Gemini CLI, iFlow) untuk tugas-tugas yang tidak penting -4. Tetapkan anggaran biaya per kunci API: Dasbor → Kunci API → Anggaran +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Men-debug +## Debugging -### Aktifkan Log Permintaan +### Enable Request Logs -Setel `ENABLE_REQUEST_LOGS=true` di file `.env` Anda. Log muncul di bawah direktori `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Periksa Kesehatan Penyedia +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Penyimpanan Waktu Proses +### Runtime Storage -- Status utama: `${DATA_DIR}/db.json` (penyedia, kombo, alias, kunci, pengaturan) -- Penggunaan: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Log permintaan: `/logs/...` (saat `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Masalah Pemutus Arus +## Circuit Breaker Issues -### Penyedia terjebak dalam keadaan TERBUKA +### Provider stuck in OPEN state -Ketika pemutus arus penyedia TERBUKA, permintaan diblokir hingga cooldown berakhir. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Perbaikan:** +**Fix:** -1. Buka **Dasbor → Pengaturan → Ketahanan** -2. Periksa kartu pemutus arus untuk penyedia yang terpengaruh -3. Klik **Reset Semua** untuk menghapus semua pemutus, atau tunggu hingga cooldown berakhir -4. Pastikan penyedia benar-benar tersedia sebelum melakukan reset +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Penyedia terus membuat pemutus arus tersandung +### Provider keeps tripping the circuit breaker -Jika penyedia berulang kali memasuki status OPEN: +If a provider repeatedly enters OPEN state: -1. Periksa **Dasbor → Kesehatan → Kesehatan Penyedia** untuk mengetahui pola kegagalannya -2. Buka **Pengaturan → Ketahanan → Profil Penyedia** dan tingkatkan ambang kegagalan -3. Periksa apakah penyedia telah mengubah batas API atau memerlukan autentikasi ulang -4. Tinjau telemetri latensi — latensi tinggi dapat menyebabkan kegagalan berbasis waktu habis +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Masalah Transkripsi Audio +## Audio Transcription Issues -### Kesalahan "Model tidak didukung". +### "Unsupported model" error -- Pastikan Anda menggunakan awalan yang benar: `deepgram/nova-3` atau `assemblyai/best` -- Verifikasi penyedia terhubung di **Dasbor → Penyedia** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Transkripsi kembali kosong atau gagal +### Transcription returns empty or fails -- Periksa format audio yang didukung: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Pastikan ukuran file berada dalam batas penyedia (biasanya <25MB) -- Periksa validitas kunci API penyedia di kartu penyedia +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Proses Debug Penerjemah +## Translator Debugging -Gunakan **Dasbor → Penerjemah** untuk men-debug masalah terjemahan format: +Use **Dashboard → Translator** to debug format translation issues: -| Modus | Kapan Menggunakan | -| -------------------- | -------------------------------------------------------------------------------------------------------------------- | -| **Taman bermain** | Bandingkan format masukan/keluaran secara berdampingan — tempelkan permintaan yang gagal untuk melihat terjemahannya | -| **Penguji Obrolan** | Kirim pesan langsung dan periksa muatan permintaan/respons lengkap termasuk header | -| **Bangku Tes** | Jalankan pengujian batch di seluruh kombinasi format untuk menemukan terjemahan mana yang rusak | -| **Monitor Langsung** | Tonton alur permintaan waktu nyata untuk mengetahui masalah terjemahan yang terputus-putus | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Masalah format umum +### Common format issues -- **Tag berpikir tidak muncul** — Periksa apakah penyedia target mendukung pemikiran dan pengaturan anggaran pemikiran -- **Panggilan alat terputus** — Beberapa terjemahan format mungkin menghapus bidang yang tidak didukung; verifikasi dalam mode Taman Bermain -- **Perintah sistem hilang** — Claude dan Gemini menangani perintah sistem secara berbeda; periksa keluaran terjemahan -- **SDK mengembalikan string mentah, bukan objek** — Diperbaiki di v1.1.0: pembersih respons sekarang menghapus kolom non-standar (`x_groq`, `usage_breakdown`, dll.) yang menyebabkan kegagalan validasi OpenAI SDK Pydantic -- **GLM/ERNIE menolak peran `system`** — Diperbaiki di v1.1.0: penormal peran secara otomatis menggabungkan pesan sistem ke dalam pesan pengguna untuk model yang tidak kompatibel -- **Peran `developer` tidak dikenali** — Diperbaiki di v1.1.0: otomatis dikonversi ke `system` untuk penyedia non-OpenAI -- **`json_schema` tidak berfungsi dengan Gemini** — Diperbaiki di v1.1.0: `response_format` kini dikonversi ke `responseMimeType` + `responseSchema` Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Pengaturan Ketahanan +## Resilience Settings -### Batas tarif otomatis tidak terpicu +### Auto rate-limit not triggering -- Batas tarif otomatis hanya berlaku untuk penyedia kunci API (bukan OAuth/langganan) -- Verifikasi **Pengaturan → Ketahanan → Profil Penyedia** telah mengaktifkan batas tarif otomatis -- Periksa apakah penyedia mengembalikan kode status `429` atau header `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Menyetel backoff eksponensial +### Tuning exponential backoff -Profil penyedia mendukung pengaturan berikut: +Provider profiles support these settings: -- **Penundaan dasar** — Waktu tunggu awal setelah kegagalan pertama (default: 1 detik) -- **Penundaan maksimal** — Batas waktu tunggu maksimum (default: 30 detik) -- **Pengganda** — Berapa banyak peningkatan penundaan per kegagalan berturut-turut (default: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Kawanan anti petir +### Anti-thundering herd -Ketika banyak permintaan bersamaan mencapai penyedia dengan tarif terbatas, OmniRoute menggunakan mutex + pembatasan tarif otomatis untuk membuat serialisasi permintaan dan mencegah kegagalan berjenjang. Ini otomatis untuk penyedia kunci API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Masih Terjebak? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Masalah GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arsitektur**: Lihat [link](ARCHITECTURE.md) untuk detail internal -- **Referensi API**: Lihat [link](API_REFERENCE.md) untuk semua titik akhir -- **Dasbor Kesehatan**: Periksa **Dasbor → Kesehatan** untuk status sistem waktu nyata -- **Penerjemah**: Gunakan **Dasbor → Penerjemah** untuk men-debug masalah format +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/id/USER_GUIDE.md b/docs/i18n/id/USER_GUIDE.md index 85fdaa70ea..5a043224df 100644 --- a/docs/i18n/id/USER_GUIDE.md +++ b/docs/i18n/id/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Panduan Pengguna +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Panduan lengkap untuk mengonfigurasi penyedia, membuat kombo, mengintegrasikan alat CLI, dan menerapkan OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Daftar Isi +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Panduan lengkap untuk mengonfigurasi penyedia, membuat kombo, mengintegrasikan a --- -## 💰 Sekilas tentang Harga +## 💰 Pricing at a Glance -| Tingkat | Penyedia | Biaya | Reset Kuota | Terbaik Untuk | -| ------------------- | ----------------- | -------------------- | ------------------------- | --------------------------- | -| **💳 BERLANGGANAN** | Kode Claude (Pro) | $20/bln | 5 jam + mingguan | Sudah berlangganan | -| | Kodeks (Plus/Pro) | $20-200/bln | 5 jam + mingguan | Pengguna OpenAI | -| | CLI Gemini | **GRATIS** | 180K/bln + 1K/hari | Setiap orang! | -| | Kopilot GitHub | $10-19/bln | Bulanan | Pengguna GitHub | -| **🔑 KUNCI API** | Pencarian Dalam | Bayar per penggunaan | Tidak ada | Alasan murah | -| | Bagus | Bayar per penggunaan | Tidak ada | Inferensi ultra-cepat | -| | xAI (Grok) | Bayar per penggunaan | Tidak ada | Alasan Grok 4 | -| | Mistral | Bayar per penggunaan | Tidak ada | Model yang dihosting di UE | -| | Kebingungan | Bayar per penggunaan | Tidak ada | Ditambah pencarian | -| | Bersama AI | Bayar per penggunaan | Tidak ada | Model sumber terbuka | -| | AI kembang api | Bayar per penggunaan | Tidak ada | Gambar FLUX Cepat | -| | Otak | Bayar per penggunaan | Tidak ada | Kecepatan skala wafer | -| | menyatu | Bayar per penggunaan | Tidak ada | Perintah R+ RAG | -| | NVIDIA NIM | Bayar per penggunaan | Tidak ada | Model perusahaan | -| **💰 MURAH** | GLM-4.7 | $0,6/1 juta | Setiap hari pukul 10 pagi | Cadangan anggaran | -| | MiniMax M2.1 | $0,2/1 juta | 5 jam bergulir | Pilihan termurah | -| | Kimi K2 | $9/bln tetap | 10 juta token/bln | Biaya yang dapat diprediksi | -| **🆓 GRATIS** | iFlow | $0 | Tidak terbatas | 8 model gratis | -| | Qwen | $0 | Tidak terbatas | 3 model gratis | -| | Kiro | $0 | Tidak terbatas | Claude gratis | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Kiat Pro:** Mulai dengan Gemini CLI (gratis 180 ribu/bulan) + kombo iFlow (gratis tanpa batas) = ​​biaya $0! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Kasus Penggunaan +## 🎯 Use Cases -### Kasus 1: "Saya berlangganan Claude Pro" +### Case 1: "I have Claude Pro subscription" -**Masalah:** Kuota habis tanpa terpakai, batas kecepatan selama coding berat +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Kasus 2: "Saya ingin tanpa biaya" +### Case 2: "I want zero cost" -**Masalah:** Tidak mampu berlangganan, memerlukan pengkodean AI yang andal +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Kasus 3: "Saya memerlukan pengkodean 24/7, tanpa gangguan" +### Case 3: "I need 24/7 coding, no interruptions" -**Masalah:** Tenggat waktu, tidak mampu membayar downtime +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Kasus 4: "Saya ingin AI GRATIS di OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Masalah:** Membutuhkan asisten AI dalam aplikasi perpesanan, sepenuhnya gratis +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Pengaturan Penyedia +## 📖 Provider Setup -### 🔐 Penyedia Langganan +### 🔐 Subscription Providers -#### Kode Claude (Pro/Maks) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Kiat Pro:** Gunakan Opus untuk tugas kompleks, Soneta untuk kecepatan. OmniRoute melacak kuota per model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### Kodeks OpenAI (Plus/Pro) +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (GRATIS 180K/bulan!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Nilai Terbaik:** Tingkat gratis yang sangat besar! Gunakan ini sebelum tingkatan berbayar. +**Best Value:** Huge free tier! Use this before paid tiers. -#### Kopilot GitHub +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Penyedia Murah +### 💰 Cheap Providers -#### GLM-4.7 (Reset harian, $0,6/1 juta) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Daftar: [Zhipu AI](https://open.bigmodel.cn/) -2. Dapatkan kunci API dari Coding Plan -3. Dasbor → Tambahkan Kunci API: Penyedia: `glm`, Kunci API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Gunakan:** `glm/glm-4.7` — **Tips Pro:** Paket Coding menawarkan 3× kuota dengan biaya 1/7! Reset setiap hari pukul 10.00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (reset 5 jam, $0,20/1 juta) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Daftar: [MiniMax](https://www.minimax.io/) -2. Dapatkan kunci API → Dasbor → Tambahkan Kunci API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Gunakan:** `minimax/MiniMax-M2.1` — **Tips Pro:** Opsi termurah untuk konteks panjang (1 juta token)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/bulan tetap) +#### Kimi K2 ($9/month flat) -1. Berlangganan: [Moonshot AI](https://platform.moonshot.ai/) -2. Dapatkan kunci API → Dasbor → Tambahkan Kunci API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Penggunaan:** `kimi/kimi-latest` — **Tips Pro:** Memperbaiki $9/bulan untuk 10 juta token = biaya efektif $0,90/1 juta! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 Penyedia GRATIS +### 🆓 FREE Providers -#### iFlow (8 model GRATIS) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 model GRATIS) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRATIS) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Kombo +## 🎨 Combos -### Contoh 1: Maksimalkan Langganan → Cadangan Murah +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Contoh 2: Gratis Saja (Tanpa Biaya) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 Integrasi CLI +## 🔧 CLI Integration -### IDE Kursor +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Kode Claude +### Claude Code -Sunting `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Sunting `~/.claude/config.json`: } ``` -### Kodeks CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -279,9 +279,9 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### Buka Cakar +### OpenClaw -Sunting `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Sunting `~/.openclaw/openclaw.json`: } ``` -**Atau gunakan Dasbor:** Alat CLI → OpenClaw → Konfigurasi otomatis +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Lanjutkan / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Penerapan +## 🚀 Deployment -### Penerapan VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### buruh pelabuhan +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Untuk mode terintegrasi host dengan biner CLI, lihat bagian Docker di dokumen utama. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Variabel Lingkungan +### Environment Variables -| Variabel | Bawaan | Deskripsi | -| --------------------- | ------------------------------------ | --------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Rahasia penandatanganan JWT (**perubahan produksi**) | -| `INITIAL_PASSWORD` | `123456` | Kata sandi masuk pertama | -| `DATA_DIR` | `~/.omniroute` | Direktori data (db, penggunaan, log) | -| `PORT` | kerangka default | Port layanan (`20128` dalam contoh) | -| `HOSTNAME` | kerangka default | Ikat host (Docker defaultnya adalah `0.0.0.0`) | -| `NODE_ENV` | default waktu proses | Tetapkan `production` untuk diterapkan | -| `BASE_URL` | `http://localhost:20128` | URL dasar internal sisi server | -| `CLOUD_URL` | `https://omniroute.dev` | URL dasar titik akhir sinkronisasi cloud | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Rahasia HMAC untuk kunci API yang dihasilkan | -| `REQUIRE_API_KEY` | `false` | Terapkan kunci API Pembawa di `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Mengaktifkan log permintaan/respons | -| `AUTH_COOKIE_SECURE` | `false` | Paksa cookie autentikasi `Secure` (di belakang proksi terbalik HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Untuk referensi variabel lingkungan selengkapnya, lihat [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Model yang Tersedia +## 📊 Available Models
-Lihat semua model yang tersedia +View all available models -**Kode Claude (`cc/`)** — Pro/Maks: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Kodeks (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Copilot GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — $0,6/1 juta: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $0,2/1 juta: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,15 +460,15 @@ Untuk referensi variabel lingkungan selengkapnya, lihat [README](../README.md). **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Kebingungan (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Bersama AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**AI Kembang Api (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Otak Otak (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Di sini (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Untuk referensi variabel lingkungan selengkapnya, lihat [README](../README.md). --- -## 🧩 Fitur Lanjutan +## 🧩 Advanced Features -### Model Khusus +### Custom Models -Tambahkan ID model apa pun ke penyedia mana pun tanpa menunggu pembaruan aplikasi: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Atau gunakan Dasbor: **Penyedia → [Penyedia] → Model Khusus**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Rute Penyedia Khusus +### Dedicated Provider Routes -Rutekan permintaan langsung ke penyedia tertentu dengan validasi model: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Awalan penyedia ditambahkan secara otomatis jika tidak ada. Model yang tidak cocok menampilkan `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Konfigurasi Proksi Jaringan +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Prioritas:** Khusus kunci → Khusus kombo → Khusus penyedia → Global → Lingkungan. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API Katalog Model +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Mengembalikan model yang dikelompokkan berdasarkan penyedia dengan tipe (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Sinkronisasi Awan +### Cloud Sync -- Sinkronisasi penyedia, kombo, dan pengaturan di seluruh perangkat -- Sinkronisasi latar belakang otomatis dengan batas waktu + cepat gagal -- Lebih memilih `BASE_URL`/`CLOUD_URL` sisi server dalam produksi +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (Fase 9) +### LLM Gateway Intelligence (Phase 9) -- **Cache Semantik** — Cache otomatis non-streaming, suhu=0 tanggapan (bypass dengan `X-OmniRoute-No-Cache: true`) -- **Idempotency Permintaan** — Menghapus duplikat permintaan dalam waktu 5 detik melalui header `Idempotency-Key` atau `X-Request-Id` -- **Pelacakan Kemajuan** — Ikut serta dalam acara SSE `event: progress` melalui header `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Taman Bermain Penerjemah +### Translator Playground -Akses melalui **Dasbor → Penerjemah**. Debug dan visualisasikan bagaimana OmniRoute menerjemahkan permintaan API antar penyedia. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Modus | Tujuan | -| -------------------- | ------------------------------------------------------------------------------------------------ | -| **Taman bermain** | Pilih format sumber/target, tempelkan permintaan, dan lihat keluaran terjemahan secara instan | -| **Penguji Obrolan** | Kirim pesan obrolan langsung melalui proxy dan periksa siklus permintaan/respons lengkap | -| **Bangku Tes** | Jalankan pengujian batch pada berbagai kombinasi format untuk memverifikasi kebenaran terjemahan | -| **Monitor Langsung** | Tonton terjemahan real-time saat permintaan mengalir melalui proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Kasus penggunaan:** +**Use cases:** -- Debug mengapa kombinasi klien/penyedia tertentu gagal -- Verifikasi bahwa tag pemikiran, panggilan alat, dan perintah sistem diterjemahkan dengan benar -- Bandingkan perbedaan format antara format OpenAI, Claude, Gemini, dan Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Strategi Perutean +### Routing Strategies -Konfigurasikan melalui **Dasbor → Pengaturan → Perutean**. +Configure via **Dashboard → Settings → Routing**. -| Strategi | Deskripsi | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------- | -| **Isi Dulu** | Menggunakan akun dalam urutan prioritas — akun utama menangani semua permintaan hingga tidak tersedia | -| **Robin Bulat** | Menggilir semua akun dengan batas melekat yang dapat dikonfigurasi (default: 3 panggilan per akun) | -| **P2C (Kekuatan Dua Pilihan)** | Pilih 2 akun acak dan rute ke akun yang lebih sehat — menyeimbangkan beban dengan kesadaran akan kesehatan | -| **Acak** | Memilih akun secara acak untuk setiap permintaan menggunakan Fisher-Yates shuffle | -| **Jarang Digunakan** | Merutekan ke akun dengan stempel waktu `lastUsedAt` terlama, mendistribusikan lalu lintas secara merata | -| **Pengoptimalan Biaya** | Merutekan ke akun dengan nilai prioritas terendah, mengoptimalkan penyedia berbiaya terendah | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Alias Model Wildcard +#### Wildcard Model Aliases -Buat pola wildcard untuk memetakan ulang nama model: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Wildcard mendukung `*` (karakter apa saja) dan `?` (karakter tunggal). +Wildcards support `*` (any characters) and `?` (single character). -#### Rantai Pengganti +#### Fallback Chains -Tentukan rantai fallback global yang berlaku di semua permintaan: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Ketahanan & Pemutus Sirkuit +### Resilience & Circuit Breakers -Konfigurasikan melalui **Dasbor → Pengaturan → Ketahanan**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute mengimplementasikan ketahanan tingkat penyedia dengan empat komponen: +OmniRoute implements provider-level resilience with four components: -1. **Profil Penyedia** — Konfigurasi per penyedia untuk: - - Ambang batas kegagalan (berapa banyak kegagalan sebelum dibuka) - - Durasi pendinginan - - Sensitivitas deteksi batas kecepatan - - Parameter backoff eksponensial +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Batas Tarif yang Dapat Diedit** — Default tingkat sistem dapat dikonfigurasi di dasbor: - - **Permintaan Per Menit (RPM)** — Permintaan maksimum per menit per akun - - **Waktu Minimum Antar Permintaan** — Kesenjangan minimum dalam milidetik antar permintaan - - **Permintaan Bersamaan Maksimum** — Permintaan simultan maksimum per akun - - Klik **Edit** untuk mengubah, lalu **Simpan** atau **Batal**. Nilai-nilai bertahan melalui API ketahanan. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Pemutus Sirkuit** — Melacak kegagalan per penyedia dan secara otomatis membuka sirkuit ketika ambang batas tercapai: - - **TUTUP** (Sehat) — Permintaan mengalir normal - - **BUKA** — Penyedia diblokir sementara setelah kegagalan berulang kali - - **HALF_OPEN** — Menguji apakah penyedia telah pulih +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Kebijakan & Pengidentifikasi Terkunci** — Menampilkan status pemutus sirkuit dan pengidentifikasi terkunci dengan kemampuan buka paksa. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Deteksi Otomatis Batas Tarif** — Memantau header `429` dan `Retry-After` untuk secara proaktif menghindari batas tarif penyedia. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Kiat Pro:** Gunakan tombol **Reset Semua** untuk menghapus semua pemutus sirkuit dan cooldown saat penyedia pulih dari pemadaman listrik. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Ekspor/Impor Basis Data +### Database Export / Import -Kelola cadangan basis data di **Dasbor → Pengaturan → Sistem & Penyimpanan**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Aksi | Deskripsi | -| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| **Ekspor Basis Data** | Mengunduh database SQLite saat ini sebagai file `.sqlite` | -| **Ekspor Semua (.tar.gz)** | Mengunduh arsip cadangan lengkap termasuk: basis data, pengaturan, kombo, koneksi penyedia (tanpa kredensial), metadata kunci API | -| **Impor Basis Data** | Unggah file `.sqlite` untuk menggantikan database saat ini. Cadangan pra-impor dibuat secara otomatis | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Validasi Impor:** File yang diimpor divalidasi integritasnya (pemeriksaan pragma SQLite), tabel yang diperlukan (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), dan ukuran (maks 100MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Kasus Penggunaan:** +**Use Cases:** -- Migrasi OmniRoute antar mesin -- Buat cadangan eksternal untuk pemulihan bencana -- Bagikan konfigurasi antar anggota tim (ekspor semua → bagikan arsip) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Pengaturan Dasbor +### Settings Dashboard -Halaman pengaturan disusun menjadi 5 tab untuk memudahkan navigasi: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Isi | -| ------------- | ------------------------------------------------------------------------------------------------------------- | -| **Keamanan** | Pengaturan Login/Kata Sandi, Kontrol Akses IP, Autentikasi API untuk `/models`, dan Pemblokiran Penyedia | -| **Perutean** | Strategi perutean global (6 opsi), alias model wildcard, rantai fallback, default kombo | -| **Ketahanan** | Profil penyedia, batas tarif yang dapat diedit, status pemutus sirkuit, kebijakan & pengidentifikasi terkunci | -| **AI** | Memikirkan konfigurasi anggaran, injeksi cepat sistem global, statistik cache cepat | -| **Lanjutan** | Konfigurasi proksi global (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Biaya & Manajemen Anggaran +### Costs & Budget Management -Akses melalui **Dasbor → Biaya**. +Access via **Dashboard → Costs**. -| Tab | Tujuan | -| ------------ | ---------------------------------------------------------------------------------------------------------- | -| **Anggaran** | Tetapkan batas pengeluaran per kunci API dengan anggaran harian/mingguan/bulanan dan pelacakan waktu nyata | -| **Harga** | Lihat dan edit entri harga model — biaya per 1K token input/output per penyedia | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Pelacakan Biaya:** Setiap permintaan mencatat penggunaan token dan menghitung biaya menggunakan tabel harga. Lihat pengelompokan di **Dasbor → Penggunaan** menurut penyedia, model, dan kunci API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Transkripsi Audio +### Audio Transcription -OmniRoute mendukung transkripsi audio melalui titik akhir yang kompatibel dengan OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Penyedia yang tersedia: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Format audio yang didukung: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Strategi Penyeimbangan Kombo +### Combo Balancing Strategies -Konfigurasikan penyeimbangan per kombo di **Dasbor → Kombo → Buat/Edit → Strategi**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategi | Deskripsi | -| ---------------------- | -------------------------------------------------------------------------------------- | -| **Robin Bulat** | Berputar melalui model secara berurutan | -| **Prioritas** | Selalu mencoba model pertama; jatuh kembali hanya karena kesalahan | -| **Acak** | Memilih model acak dari kombo untuk setiap permintaan | -| **Berbobot** | Rute secara proporsional berdasarkan bobot yang ditetapkan per model | -| **Jarang Digunakan** | Merutekan ke model dengan permintaan terkini paling sedikit (menggunakan metrik kombo) | -| **Dioptimalkan Biaya** | Rute ke model termurah yang tersedia (menggunakan tabel harga) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Default kombo global dapat diatur di **Dasbor → Pengaturan → Perutean → Default Kombo**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Dasbor Kesehatan +### Health Dashboard -Akses melalui **Dasbor → Kesehatan**. Ikhtisar kesehatan sistem real-time dengan 6 kartu: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Kartu | Apa yang Ditunjukkannya | -| ---------------------- | ----------------------------------------------------------------------- | -| **Status Sistem** | Uptime, versi, penggunaan memori, direktori data | -| **Kesehatan Penyedia** | Status pemutus sirkuit per penyedia (Tertutup/Terbuka/Setengah Terbuka) | -| **Batas Tarif** | Cooldown batas tarif aktif per akun dengan sisa waktu | -| **Penguncian Aktif** | Penyedia diblokir sementara oleh kebijakan lockout | -| **Cache Tanda Tangan** | Statistik cache deduplikasi (kunci aktif, tingkat hit) | -| **Telemetri Latensi** | agregasi latensi p50/p95/p99 per penyedia | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Tips Pro:** Halaman Kesehatan disegarkan secara otomatis setiap 10 detik. Gunakan kartu pemutus sirkuit untuk mengidentifikasi penyedia mana yang mengalami masalah. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/in/API_REFERENCE.md b/docs/i18n/in/API_REFERENCE.md index 7339b1e9a9..b795722c11 100644 --- a/docs/i18n/in/API_REFERENCE.md +++ b/docs/i18n/in/API_REFERENCE.md @@ -1,12 +1,12 @@ -# एपीआई संदर्भ +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -सभी ओमनीरूट एपीआई एंडपॉइंट के लिए पूरा संदर्भ। +Complete reference for all OmniRoute API endpoints. --- -## सामग्री तालिका +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## चैट समापन +## Chat Completions ```bash POST /v1/chat/completions @@ -36,23 +36,34 @@ Content-Type: application/json } ``` -### कस्टम हेडर +### Custom Headers -| हेडर | दिशा | विवरण | -| ------------------------ | ----------- | -------------------------------------------- | ----- | -| `X-OmniRoute-No-Cache` | निवेदन | कैश को बायपास करने के लिए `true` पर सेट करें | -| `X-OmniRoute-Progress` | निवेदन | प्रगति घटनाओं के लिए `true` पर सेट करें | -| `Idempotency-Key` | निवेदन | डेडअप कुंजी (5एस विंडो) | -| | निवेदन | वैकल्पिक डिडअप कुंजी | -| `X-OmniRoute-Cache` | प्रतिक्रिया | `HIT` या `MISS` (गैर-स्ट्रीमिंग) | -| `X-OmniRoute-Idempotent` | प्रतिक्रिया | `true` यदि डुप्लीकेट काटा गया है | -| `X-OmniRoute-Progress` | प्रतिक्रिया | `enabled` यदि प्रगति ट्रैकिंग | पर है | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## एम्बेडिंग +## Embeddings -उपलब्ध प्रदाता: नेबियस, ओपनएआई, मिस्ट्रल, टुगेदर एआई, फायरवर्क्स, एनवीआईडीआईए। +```bash +POST /v1/embeddings +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "nebius/Qwen/Qwen3-Embedding-8B", + "input": "The food was delicious" +} +``` + +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -61,7 +72,7 @@ GET /v1/embeddings --- -## छवि निर्माण +## Image Generation ```bash POST /v1/images/generations @@ -75,7 +86,7 @@ Content-Type: application/json } ``` -उपलब्ध प्रदाता: OpenAI (DALL-E), xAI (ग्रोक इमेज), टुगेदर AI (FLUX), फायरवर्क्स AI। +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -84,32 +95,45 @@ GET /v1/images/generations --- -## सूची मॉडल +## List Models + +```bash +GET /v1/models +Authorization: Bearer your-api-key + +→ Returns all chat, embedding, and image models + combos in OpenAI format +``` --- -## संगतता समापन बिंदु +## Compatibility Endpoints -| विधि | पथ | प्रारूप | -| ------------ | --------------------------- | -------------------- | -| पोस्ट | `/v1/chat/completions` | ओपनएआई | -| पोस्ट | `/v1/messages` | मानवशास्त्रीय | -| पोस्ट | `/v1/responses` | ओपनएआई प्रतिक्रियाएँ | -| पोस्ट | `/v1/embeddings` | ओपनएआई | -| पोस्ट | `/v1/images/generations` | ओपनएआई | -| प्राप्त करें | `/v1/models` | ओपनएआई | -| पोस्ट | `/v1/messages/count_tokens` | मानवशास्त्रीय | -| प्राप्त करें | `/v1beta/models` | मिथुन | -| पोस्ट | `/v1beta/models/{...path}` | मिथुन जनरेटकंटेंट | -| पोस्ट | `/v1/api/chat` | ओलामा | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### समर्पित प्रदाता मार्ग +### Dedicated Provider Routes -गायब होने पर प्रदाता उपसर्ग स्वतः जुड़ जाता है। बेमेल मॉडल `400` लौटाते हैं। +```bash +POST /v1/providers/{provider}/chat/completions +POST /v1/providers/{provider}/embeddings +POST /v1/providers/{provider}/images/generations +``` + +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## सिमेंटिक कैश +## Semantic Cache ```bash # Get cache stats @@ -119,60 +143,75 @@ GET /api/cache DELETE /api/cache ``` -प्रतिक्रिया उदाहरण: +Response example: + +```json +{ + "semanticCache": { + "memorySize": 42, + "memoryMaxSize": 500, + "dbSize": 128, + "hitRate": 0.65 + }, + "idempotency": { + "activeKeys": 3, + "windowMs": 5000 + } +} +``` --- -## डैशबोर्ड एवं प्रबंधन +## Dashboard & Management -### प्रमाणीकरण +### Authentication -| समापन बिंदु | Method | विवरण | +| Endpoint | Method | Description | | ----------------------------- | ------- | --------------------- | | `/api/auth/login` | POST | Login | -| `/api/auth/logout` | POST | लॉगआउट | +| `/api/auth/logout` | POST | Logout | | `/api/settings/require-login` | GET/PUT | Toggle login required | ### Provider Management -| समापन बिंदु | Method | विवरण | -| ---------------------------- | ----------------------------- | ---------------------------------- | -| `/api/providers` | GET/POST | प्रदाताओं की सूची बनाएं/बनाएँ | -| `/api/providers/[id]` | GET/PUT/DELETE | एक प्रदाता प्रबंधित करें | -| `/api/providers/[id]/test` | पोस्ट | परीक्षण प्रदाता कनेक्शन | -| `/api/providers/[id]/models` | GET | सूची प्रदाता मॉडल | -| `/api/providers/validate` | POST | प्रदाता कॉन्फ़िगरेशन सत्यापित करें | -| `/api/provider-nodes*` | Various | प्रदाता नोड प्रबंधन | -| `/api/provider-models` | प्राप्त करें/पोस्ट करें/हटाएं | कस्टम मॉडल | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | ### OAuth Flows -| समापन बिंदु | Method | विवरण | -| -------------------------------- | ------ | --------------------- | -| `/api/oauth/[provider]/[action]` | विविध | प्रदाता-विशिष्ट OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### रूटिंग और कॉन्फ़िगरेशन +### Routing & Config -| Endpoint | Method | विवरण | -| --------------------- | ------------ | -------------------------------- | -| `/api/models/alias` | GET/POST | मॉडल उपनाम | -| `/api/models/catalog` | प्राप्त करें | प्रदाता द्वारा सभी मॉडल + प्रकार | -| `/api/combos*` | विविध | कॉम्बो प्रबंधन | -| `/api/keys*` | Various | एपीआई कुंजी प्रबंधन | -| `/api/pricing` | प्राप्त करें | मॉडल मूल्य निर्धारण | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### उपयोग एवं विश्लेषण +### Usage & Analytics -| समापन बिंदु | विधि | Description | -| --------------------------- | ------------ | -------------------- | -| `/api/usage/history` | प्राप्त करें | उपयोग इतिहास | -| `/api/usage/logs` | प्राप्त करें | Usage logs | -| `/api/usage/request-logs` | प्राप्त करें | Request-level logs | -| `/api/usage/[connectionId]` | प्राप्त करें | Per-connection usage | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | ### Settings -| समापन बिंदु | Method | Description | +| Endpoint | Method | Description | | ------------------------------- | ------- | ---------------------- | | `/api/settings` | GET/PUT | General settings | | `/api/settings/proxy` | GET/PUT | Network proxy config | @@ -183,94 +222,104 @@ DELETE /api/cache ### Monitoring -| समापन बिंदु | विधि | विवरण | -| ------------------------ | ------------------ | -------------------- | -| `/api/sessions` | प्राप्त करें | सक्रिय सत्र ट्रैकिंग | -| `/api/rate-limits` | प्राप्त करें | प्रति खाता दर सीमा | -| `/api/monitoring/health` | प्राप्त करें | स्वास्थ्य जांच | -| `/api/cache` | प्राप्त करें/हटाएं | कैश आँकड़े / साफ़ | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### बैकअप और निर्यात/आयात +### Backup & Export/Import -| समापन बिंदु | विधि | विवरण | -| --------------------------- | ------------ | -------------------------------------------------- | -| `/api/db-backups` | प्राप्त करें | उपलब्ध बैकअप की सूची | -| `/api/db-backups` | डालो | मैन्युअल बैकअप बनाएं | -| `/api/db-backups` | पोस्ट | किसी विशिष्ट बैकअप से पुनर्स्थापित करें | -| `/api/db-backups/export` | प्राप्त करें | डेटाबेस को .sqlite फ़ाइल के रूप में डाउनलोड करें | -| `/api/db-backups/import` | पोस्ट | डेटाबेस को बदलने के लिए .sqlite फ़ाइल अपलोड करें | -| `/api/db-backups/exportAll` | प्राप्त करें | .tar.gz संग्रह के रूप में पूर्ण बैकअप डाउनलोड करें | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### क्लाउड सिंक +### Cloud Sync -| समापन बिंदु | विधि | विवरण | -| ---------------------- | ----- | ------------------ | -| `/api/sync/cloud` | विविध | क्लाउड सिंक ऑपरेशन | -| `/api/sync/initialize` | पोस्ट | सिंक प्रारंभ करें | -| `/api/cloud/*` | विविध | बादल प्रबंधन | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### सीएलआई उपकरण +### CLI Tools -| समापन बिंदु | विधि | विवरण | -| ---------------------------------- | ------------ | --------------------- | -| `/api/cli-tools/claude-settings` | प्राप्त करें | क्लाउड सीएलआई स्थिति | -| `/api/cli-tools/codex-settings` | प्राप्त करें | कोडेक्स सीएलआई स्थिति | -| `/api/cli-tools/droid-settings` | प्राप्त करें | Droid CLI स्थिति | -| `/api/cli-tools/openclaw-settings` | प्राप्त करें | ओपनक्लॉ सीएलआई स्थिति | -| | प्राप्त करें | जेनेरिक सीएलआई रनटाइम | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -सीएलआई प्रतिक्रियाओं में शामिल हैं: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`। +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### लचीलापन और दर सीमाएँ +### ACP Agents -| समापन बिंदु | विधि | विवरण | -| ----------------------- | ------------- | ------------------------------------- | -| `/api/resilience` | प्राप्त/डालें | लचीलापन प्रोफ़ाइल प्राप्त/अद्यतन करें | -| `/api/resilience/reset` | पोस्ट | सर्किट ब्रेकर रीसेट करें | -| `/api/rate-limits` | प्राप्त करें | प्रति खाता दर सीमा स्थिति | -| `/api/rate-limit` | प्राप्त करें | वैश्विक दर सीमा विन्यास | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### मूल्यांकन +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| समापन बिंदु | विधि | विवरण | -| ------------ | ------------------ | ----------------------------- | -| `/api/evals` | प्राप्त/पोस्ट करें | सूची eval सुइट्स/रन मूल्यांकन | +### Resilience & Rate Limits -### नीतियां +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| समापन बिंदु | विधि | विवरण | -| --------------- | ----------------------------- | ---------------------------- | -| `/api/policies` | प्राप्त करें/पोस्ट करें/हटाएं | रूटिंग नीतियां प्रबंधित करें | +### Evals -### अनुपालन +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| समापन बिंदु | विधि | विवरण | -| --------------------------- | ------------ | --------------------------- | -| `/api/compliance/audit-log` | प्राप्त करें | अनुपालन ऑडिट लॉग (अंतिम एन) | +### Policies -### v1बीटा (मिथुन-संगत) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| समापन बिंदु | विधि | विवरण | -| -------------------------- | ------------ | --------------------------------------- | -| `/v1beta/models` | प्राप्त करें | जेमिनी प्रारूप में मॉडलों की सूची बनाएं | -| `/v1beta/models/{...path}` | पोस्ट | मिथुन `generateContent` समापन बिंदु | +### Compliance -ये समापन बिंदु उन ग्राहकों के लिए जेमिनी के एपीआई प्रारूप को प्रतिबिंबित करते हैं जो मूल जेमिनी एसडीके संगतता की अपेक्षा करते हैं। +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### आंतरिक/सिस्टम एपीआई +### v1beta (Gemini-Compatible) -| समापन बिंदु | विधि | विवरण | -| --------------- | ------------ | --------------------------------------------------- | -| `/api/init` | प्राप्त करें | एप्लिकेशन इनिशियलाइज़ेशन जांच (पहले रन पर प्रयुक्त) | -| `/api/tags` | प्राप्त करें | ओलामा-संगत मॉडल टैग (ओलामा ग्राहकों के लिए) | -| `/api/restart` | पोस्ट | ट्रिगर सुशोभित सर्वर पुनरारंभ | -| `/api/shutdown` | पोस्ट | ट्रिगर ग्रेसफुल सर्वर शटडाउन | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **ध्यान दें:** इन समापन बिंदुओं का उपयोग सिस्टम द्वारा आंतरिक रूप से या ओलामा क्लाइंट संगतता के लिए किया जाता है। उन्हें आम तौर पर अंतिम उपयोगकर्ताओं द्वारा नहीं बुलाया जाता है। +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## ऑडियो ट्रांसक्रिप्शन +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -278,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -डीपग्राम या असेंबलीएआई का उपयोग करके ऑडियो फ़ाइलों को ट्रांसक्राइब करें। +Transcribe audio files using Deepgram or AssemblyAI. -**अनुरोध:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -289,55 +338,114 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**प्रतिक्रिया:** +**Response:** -**समर्थित प्रदाता:** `deepgram/nova-3`, `assemblyai/best`। +```json +{ + "text": "Hello, this is the transcribed audio content.", + "task": "transcribe", + "language": "en", + "duration": 12.5 +} +``` -**समर्थित प्रारूप:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`। +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. + +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## ओलामा अनुकूलता +## Ollama Compatibility -ओलामा के एपीआई प्रारूप का उपयोग करने वाले ग्राहकों के लिए: +For clients that use Ollama's API format: -अनुरोध स्वचालित रूप से ओलामा और आंतरिक प्रारूपों के बीच अनुवादित होते हैं। +```bash +# Chat endpoint (Ollama format) +POST /v1/api/chat + +# Model listing (Ollama format) +GET /api/tags +``` + +Requests are automatically translated between Ollama and internal formats. --- -## टेलीमेट्री +## Telemetry -**प्रतिक्रिया:** +```bash +# Get latency telemetry summary (p50/p95/p99 per provider) +GET /api/telemetry/summary +``` + +**Response:** + +```json +{ + "providers": { + "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, + "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } + } +} +``` --- -## बजट +## Budget + +```bash +# Get budget status for all API keys +GET /api/usage/budget + +# Set or update a budget +POST /api/usage/budget +Content-Type: application/json + +{ + "keyId": "key-123", + "limit": 50.00, + "period": "monthly" +} +``` --- -## मॉडल उपलब्धता +## Model Availability + +```bash +# Get real-time model availability across all providers +GET /api/models/availability + +# Check availability for a specific model +POST /api/models/availability +Content-Type: application/json + +{ + "model": "claude-sonnet-4-5-20250929" +} +``` --- -## अनुरोध प्रसंस्करण +## Request Processing -1. ग्राहक `/v1/*` पर अनुरोध भेजता है -2. रूट हैंडलर `handleChat`, `handleEmbedding`, `handleAudioTranscription`, या `handleImageGeneration` को कॉल करता है। -3. मॉडल हल हो गया है (प्रत्यक्ष प्रदाता/मॉडल या उपनाम/कॉम्बो) -4. खाता उपलब्धता फ़िल्टरिंग के साथ स्थानीय डीबी से चयनित क्रेडेंशियल -5. चैट के लिए: `handleChatCore` - प्रारूप का पता लगाना, अनुवाद, कैश जांच, निष्क्रियता जांच -6. प्रदाता निष्पादक अपस्ट्रीम अनुरोध भेजता है -7. प्रतिक्रिया को क्लाइंट प्रारूप (चैट) में वापस अनुवादित किया गया या जैसा है वैसा ही लौटाया गया (एम्बेडिंग/छवियां/ऑडियो) -8. उपयोग/लॉगिंग रिकॉर्ड किया गया -9. कॉम्बो नियमों के अनुसार त्रुटियों पर फ़ॉलबैक लागू होता है +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -पूर्ण वास्तुकला संदर्भ: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## प्रमाणीकरण +## Authentication -- डैशबोर्ड रूट (`/dashboard/*`) `auth_token` कुकी का उपयोग करते हैं -- लॉगिन सहेजे गए पासवर्ड हैश का उपयोग करता है; `INITIAL_PASSWORD` पर फ़ॉलबैक -- `requireLogin` `/api/settings/require-login` के माध्यम से टॉगल करने योग्य -- `/v1/*` मार्गों को वैकल्पिक रूप से बियरर एपीआई कुंजी की आवश्यकता होती है जब `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/in/ARCHITECTURE.md b/docs/i18n/in/ARCHITECTURE.md index f7dbb2e044..258d62df53 100644 --- a/docs/i18n/in/ARCHITECTURE.md +++ b/docs/i18n/in/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# ओमनीरूट आर्किटेक्चर +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_अंतिम अद्यतन: 2026-02-18_ +_Last updated: 2026-03-04_ -## कार्यकारी सारांश +## Executive Summary -ओमनीरूट एक स्थानीय एआई रूटिंग गेटवे और नेक्स्ट.जेएस पर निर्मित डैशबोर्ड है। -यह एक एकल OpenAI-संगत एंडपॉइंट (`/v1/*`) प्रदान करता है और अनुवाद, फ़ॉलबैक, टोकन रिफ्रेश और उपयोग ट्रैकिंग के साथ कई अपस्ट्रीम प्रदाताओं के बीच ट्रैफ़िक को रूट करता है। +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -मुख्य क्षमताएं: +Core capabilities: -- सीएलआई/टूल्स के लिए ओपनएआई-संगत एपीआई सतह (28 प्रदाता) -- प्रदाता प्रारूपों में अनुरोध/प्रतिक्रिया अनुवाद -- मॉडल कॉम्बो फ़ॉलबैक (मल्टी-मॉडल अनुक्रम) -- खाता-स्तरीय फ़ॉलबैक (प्रति प्रदाता बहु-खाता) -- OAuth + एपीआई-कुंजी प्रदाता कनेक्शन प्रबंधन -- `/v1/embeddings` के माध्यम से एम्बेडिंग पीढ़ी (6 प्रदाता, 9 मॉडल) -- `/v1/images/generations` के माध्यम से छवि निर्माण (4 प्रदाता, 9 मॉडल) -- तर्क मॉडल के लिए टैग पार्सिंग (`...`) के बारे में सोचें -- सख्त ओपनएआई एसडीके संगतता के लिए प्रतिक्रिया स्वच्छता -- क्रॉस-प्रदाता अनुकूलता के लिए भूमिका सामान्यीकरण (डेवलपर→सिस्टम, सिस्टम→उपयोगकर्ता)। -- संरचित आउटपुट रूपांतरण (json_schema → जेमिनी रिस्पॉन्सस्कीमा) -- प्रदाताओं, चाबियाँ, उपनाम, कॉम्बो, सेटिंग्स, मूल्य निर्धारण के लिए स्थानीय दृढ़ता -- उपयोग/लागत ट्रैकिंग और अनुरोध लॉगिंग -- मल्टी-डिवाइस/स्टेट सिंक के लिए वैकल्पिक क्लाउड सिंक -- एपीआई एक्सेस नियंत्रण के लिए आईपी अनुमति सूची/ब्लॉकलिस्ट -- सोच बजट प्रबंधन (पासथ्रू/ऑटो/कस्टम/अनुकूली) -- वैश्विक प्रणाली शीघ्र इंजेक्शन -- सत्र ट्रैकिंग और फ़िंगरप्रिंटिंग -- प्रदाता-विशिष्ट प्रोफाइल के साथ प्रति-खाता बढ़ी हुई दर सीमित करना -- प्रदाता लचीलेपन के लिए सर्किट ब्रेकर पैटर्न -- म्यूटेक्स लॉकिंग के साथ एंटी-थंडरिंग झुंड सुरक्षा -- हस्ताक्षर-आधारित अनुरोध डिडुप्लीकेशन कैश -- डोमेन परत: मॉडल उपलब्धता, लागत नियम, फ़ॉलबैक नीति, लॉकआउट नीति -- डोमेन स्थिति दृढ़ता (फ़ॉलबैक, बजट, लॉकआउट, सर्किट ब्रेकर के लिए SQLite राइट-थ्रू कैश) -- केंद्रीकृत अनुरोध मूल्यांकन के लिए नीति इंजन (लॉकआउट → बजट → फ़ॉलबैक) -- p50/p95/p99 विलंबता एकत्रीकरण के साथ टेलीमेट्री का अनुरोध करें -- एंड-टू-एंड ट्रेसिंग के लिए सहसंबंध आईडी (एक्स-रिक्वेस्ट-आईडी)। -- एपीआई कुंजी के अनुसार ऑप्ट-आउट के साथ अनुपालन ऑडिट लॉगिंग -- एलएलएम गुणवत्ता आश्वासन के लिए इवल फ्रेमवर्क -- वास्तविक समय सर्किट ब्रेकर स्थिति के साथ लचीलापन यूआई डैशबोर्ड -- मॉड्यूलर OAuth प्रदाता (`src/lib/oauth/providers/` के अंतर्गत 12 व्यक्तिगत मॉड्यूल) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -प्राथमिक रनटाइम मॉडल: +Primary runtime model: -- `src/app/api/*` के अंतर्गत Next.js ऐप रूट डैशबोर्ड एपीआई और संगतता एपीआई दोनों को लागू करते हैं -- `src/sse/*` + `open-sse/*` में एक साझा SSE/रूटिंग कोर प्रदाता निष्पादन, अनुवाद, स्ट्रीमिंग, फ़ॉलबैक और उपयोग को संभालता है +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## दायरा और सीमाएँ +## Scope and Boundaries -### दायरे में +### In Scope -- स्थानीय गेटवे रनटाइम -- डैशबोर्ड प्रबंधन एपीआई -- प्रदाता प्रमाणीकरण और टोकन ताज़ा करें -- अनुवाद और एसएसई स्ट्रीमिंग का अनुरोध करें -- स्थानीय स्थिति + उपयोग की दृढ़ता -- वैकल्पिक क्लाउड सिंक ऑर्केस्ट्रेशन +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### दायरे से बाहर +### Out of Scope -- `NEXT_PUBLIC_CLOUD_URL` के पीछे क्लाउड सेवा कार्यान्वयन -- स्थानीय प्रक्रिया के बाहर प्रदाता एसएलए/नियंत्रण विमान -- बाहरी सीएलआई बायनेरिज़ स्वयं (क्लाउड सीएलआई, कोडेक्स सीएलआई, आदि) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## उच्च स्तरीय सिस्टम संदर्भ +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,153 +113,199 @@ flowchart LR DASH --> CLOUD ``` -## कोर रनटाइम घटक +## Core Runtime Components -## 1) एपीआई और रूटिंग लेयर (नेक्स्ट.जेएस ऐप रूट्स) +## 1) API and Routing Layer (Next.js App Routes) -मुख्य निर्देशिकाएँ: +Main directories: -- अनुकूलता एपीआई के लिए `src/app/api/v1/*` और `src/app/api/v1beta/*` -- प्रबंधन/कॉन्फ़िगरेशन एपीआई के लिए `src/app/api/*` -- अगला `next.config.mjs` मानचित्र `/v1/*` से `/api/v1/*` में पुनः लिखता है +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -महत्वपूर्ण अनुकूलता मार्ग: +Important compatibility routes: -- +- `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` - `custom: true` के साथ कस्टम मॉडल शामिल हैं -- `src/app/api/v1/embeddings/route.ts` - एम्बेडिंग जेनरेशन (6 प्रदाता) -- `src/app/api/v1/images/generations/route.ts` - छवि निर्माण (एंटीग्रेविटी/नेबियस सहित 4+ प्रदाता) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` - प्रति-प्रदाता समर्पित चैट -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` - प्रति-प्रदाता समर्पित एम्बेडिंग -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` - प्रति-प्रदाता समर्पित छवियां +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -प्रबंधन डोमेन: +Management domains: -- प्रमाणीकरण/सेटिंग्स: `src/app/api/auth/*`, `src/app/api/settings/*` -- प्रदाता/कनेक्शन: `src/app/api/providers*` -- प्रदाता नोड: `src/app/api/provider-nodes*` -- कस्टम मॉडल: `src/app/api/provider-models` (प्राप्त करें/पोस्ट करें/हटाएं) -- मॉडल कैटलॉग: `src/app/api/models/catalog` (प्राप्त करें) -- प्रॉक्सी कॉन्फ़िगरेशन: `src/app/api/settings/proxy` (प्राप्त/पुट/डिलीट) + `src/app/api/settings/proxy/test` (पोस्ट) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- कुंजी/उपनाम/कॉम्बोस/मूल्य निर्धारण: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- उपयोग: `src/app/api/usage/*` -- सिंक/क्लाउड: `src/app/api/sync/*`, `src/app/api/cloud/*` -- सीएलआई टूलींग सहायक: `src/app/api/cli-tools/*` -- आईपी फ़िल्टर: `src/app/api/settings/ip-filter` (प्राप्त/पुट) -- सोच बजट: `src/app/api/settings/thinking-budget` (प्राप्त/पुट) -- सिस्टम प्रॉम्प्ट: `src/app/api/settings/system-prompt` (प्राप्त/पुट) -- सत्र: `src/app/api/sessions` (प्राप्त करें) -- दर सीमा: `src/app/api/rate-limits` (प्राप्त करें) -- लचीलापन: `src/app/api/resilience` (प्राप्त/पैच) - प्रदाता प्रोफ़ाइल, सर्किट ब्रेकर, दर सीमा स्थिति -- लचीलापन रीसेट: `src/app/api/resilience/reset` (पोस्ट) - ब्रेकर रीसेट करें + कूलडाउन -- कैश आँकड़े: `src/app/api/cache/stats` (प्राप्त करें/हटाएँ) -- मॉडल उपलब्धता: `src/app/api/models/availability` (प्राप्त करें/पोस्ट करें) -- टेलीमेट्री: `src/app/api/telemetry/summary` (प्राप्त करें) -- बजट: `src/app/api/usage/budget` (प्राप्त/पोस्ट करें) -- फ़ॉलबैक चेन: `src/app/api/fallback/chains` (प्राप्त करें/पोस्ट करें/हटाएँ) -- अनुपालन लेखापरीक्षा: `src/app/api/compliance/audit-log` (प्राप्त करें) -- मूल्यांकन: `src/app/api/evals` (प्राप्त/पोस्ट), `src/app/api/evals/[suiteId]` (प्राप्त करें) -- नीतियां: `src/app/api/policies` (प्राप्त/पोस्ट करें) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) एसएसई + अनुवाद कोर +## 2) SSE + Translation Core -मुख्य प्रवाह मॉड्यूल: +Main flow modules: -- प्रवेश: `src/sse/handlers/chat.ts` -- कोर ऑर्केस्ट्रेशन: `open-sse/handlers/chatCore.ts` -- प्रदाता निष्पादन एडाप्टर: `open-sse/executors/*` -- प्रारूप पहचान/प्रदाता कॉन्फिगरेशन: `open-sse/services/provider.ts` -- मॉडल पार्स/रिज़ॉल्यूशन: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- खाता फ़ॉलबैक तर्क: `open-sse/services/accountFallback.ts` -- अनुवाद रजिस्ट्री: `open-sse/translator/index.ts` -- स्ट्रीम परिवर्तन: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- उपयोग निष्कर्षण/सामान्यीकरण: `open-sse/utils/usageTracking.ts` -- टैग पार्सर सोचें: `open-sse/utils/thinkTagParser.ts` -- एंबेडिंग हैंडलर: `open-sse/handlers/embeddings.ts` -- एंबेडिंग प्रदाता रजिस्ट्री: `open-sse/config/embeddingRegistry.ts` -- छवि निर्माण हैंडलर: `open-sse/handlers/imageGeneration.ts` -- छवि प्रदाता रजिस्ट्री: `open-sse/config/imageRegistry.ts` -- प्रतिक्रिया स्वच्छता: `open-sse/handlers/responseSanitizer.ts` -- भूमिका सामान्यीकरण: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -सेवाएँ (व्यावसायिक तर्क): +Services (business logic): -- खाता चयन/स्कोरिंग: `open-sse/services/accountSelector.ts` -- संदर्भ जीवनचक्र प्रबंधन: `open-sse/services/contextManager.ts` -- आईपी फ़िल्टर प्रवर्तन: `open-sse/services/ipFilter.ts` -- सत्र ट्रैकिंग: `open-sse/services/sessionManager.ts` -- डुप्लिकेशन अनुरोध: `open-sse/services/signatureCache.ts` -- सिस्टम प्रॉम्प्ट इंजेक्शन: `open-sse/services/systemPrompt.ts` -- सोच बजट प्रबंधन: `open-sse/services/thinkingBudget.ts` -- वाइल्डकार्ड मॉडल रूटिंग: `open-sse/services/wildcardRouter.ts` -- दर सीमा प्रबंधन: `open-sse/services/rateLimitManager.ts` -- सर्किट ब्रेकर: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -डोमेन परत मॉड्यूल: +Domain layer modules: -- मॉडल उपलब्धता: `src/lib/domain/modelAvailability.ts` -- लागत नियम/बजट: `src/lib/domain/costRules.ts` -- फ़ॉलबैक नीति: `src/lib/domain/fallbackPolicy.ts` -- कॉम्बो रिज़ॉल्वर: `src/lib/domain/comboResolver.ts` -- तालाबंदी नीति: `src/lib/domain/lockoutPolicy.ts` -- नीति इंजन: `src/domain/policyEngine.ts` - केंद्रीकृत तालाबंदी → बजट → फ़ॉलबैक मूल्यांकन -- त्रुटि कोड सूची: `src/lib/domain/errorCodes.ts` -- अनुरोध आईडी: `src/lib/domain/requestId.ts` -- फ़ेच टाइमआउट: `src/lib/domain/fetchTimeout.ts` -- अनुरोध टेलीमेट्री: `src/lib/domain/requestTelemetry.ts` -- अनुपालन/ऑडिट: `src/lib/domain/compliance/index.ts` -- इवल धावक: `src/lib/domain/evalRunner.ts` -- डोमेन स्थिति दृढ़ता: `src/lib/db/domainState.ts` - फ़ॉलबैक चेन, बजट, लागत इतिहास, लॉकआउट स्थिति, सर्किट ब्रेकर के लिए SQLite CRUD +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth प्रदाता मॉड्यूल (`src/lib/oauth/providers/` के अंतर्गत 12 व्यक्तिगत फ़ाइलें): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- रजिस्ट्री सूचकांक: `src/lib/oauth/providers/index.ts` -- व्यक्तिगत प्रदाता: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- पतला आवरण: `src/lib/oauth/providers.ts` - अलग-अलग मॉड्यूल से पुनः निर्यात +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) दृढ़ता परत +## 3) Persistence Layer -प्राथमिक स्थिति डीबी: +Primary state DB (SQLite): -- -- फ़ाइल: `${DATA_DIR}/db.json` (या सेट होने पर `$XDG_CONFIG_HOME/omniroute/db.json`, अन्यथा `~/.omniroute/db.json`) -- संस्थाएँ: प्रदाता कनेक्शन, प्रदाता नोड्स, मॉडल उपनाम, कॉम्बो, एपीकीज़, सेटिंग्स, मूल्य निर्धारण, **कस्टम मॉडल**, **प्रॉक्सी कॉन्फिग**, **आईपीफिल्टर**, **थिंकिंगबजट**, **सिस्टमप्रॉम्प्ट** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -उपयोग डीबी: +Usage persistence: -- `src/lib/usageDb.ts` -- फ़ाइलें: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- `localDb` के समान मूल निर्देशिका नीति का पालन करता है (`DATA_DIR`, फिर सेट होने पर `XDG_CONFIG_HOME/omniroute`) -- केंद्रित उप-मॉड्यूल में विघटित: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -डोमेन स्थिति DB (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` - डोमेन स्थिति के लिए CRUD संचालन -- तालिकाएँ (`src/lib/db/core.ts` में निर्मित): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- राइट-थ्रू कैश पैटर्न: इन-मेमोरी मैप्स रनटाइम पर आधिकारिक होते हैं; उत्परिवर्तन SQLite के साथ समकालिक रूप से लिखे जाते हैं; कोल्ड स्टार्ट पर राज्य को डीबी से बहाल किया जाता है +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) प्रामाणिक + सुरक्षा सतहें +## 4) Auth + Security Surfaces -- डैशबोर्ड कुकी प्रमाणीकरण: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- एपीआई कुंजी निर्माण/सत्यापन: `src/shared/utils/apiKey.ts` -- प्रदाता रहस्य `providerConnections` प्रविष्टियों में बने रहे -- `open-sse/utils/proxyFetch.ts` (env vars) और `open-sse/utils/networkProxy.ts` (प्रति-प्रदाता या वैश्विक रूप से कॉन्फ़िगर करने योग्य) के माध्यम से आउटबाउंड प्रॉक्सी समर्थन +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) क्लाउड सिंक +## 5) Cloud Sync -- शेड्यूलर init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- आवधिक कार्य: `src/shared/services/cloudSyncScheduler.ts` -- नियंत्रण मार्ग: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## अनुरोध जीवनचक्र (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) -## कॉम्बो + अकाउंट फ़ॉलबैक फ़्लो +```mermaid +sequenceDiagram + autonumber + participant Client as CLI/SDK Client + participant Route as /api/v1/chat/completions + participant Chat as src/sse/handlers/chat + participant Core as open-sse/handlers/chatCore + participant Model as Model Resolver + participant Auth as Credential Selector + participant Exec as Provider Executor + participant Prov as Upstream Provider + participant Stream as Stream Translator + participant Usage as usageDb + + Client->>Route: POST /v1/chat/completions + Route->>Chat: handleChat(request) + Chat->>Model: parse/resolve model or combo + + alt Combo model + Chat->>Chat: iterate combo models (handleComboChat) + end + + Chat->>Auth: getProviderCredentials(provider) + Auth-->>Chat: active account + tokens/api key + + Chat->>Core: handleChatCore(body, modelInfo, credentials) + Core->>Core: detect source format + Core->>Core: translate request to target format + Core->>Exec: execute(provider, transformedBody) + Exec->>Prov: upstream API call + Prov-->>Exec: SSE/JSON response + Exec-->>Core: response + metadata + + alt 401/403 + Core->>Exec: refreshCredentials() + Exec-->>Core: updated tokens + Core->>Exec: retry request + end + + Core->>Stream: translate/normalize stream to client format + Stream-->>Client: SSE chunks / JSON response + + Stream->>Usage: extract usage + persist history/log +``` + +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -289,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -फ़ॉलबैक निर्णय स्थिति कोड और त्रुटि-संदेश अनुमानों का उपयोग करके `open-sse/services/accountFallback.ts` द्वारा संचालित होते हैं। +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth ऑनबोर्डिंग और टोकन रिफ्रेश जीवनचक्र +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -321,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -लाइव ट्रैफ़िक के दौरान रिफ्रेश को निष्पादक `refreshCredentials()` के माध्यम से `open-sse/handlers/chatCore.ts` के अंदर निष्पादित किया जाता है। +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## क्लाउड सिंक जीवनचक्र (सक्षम/सिंक/अक्षम) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -355,249 +401,383 @@ sequenceDiagram Sync-->>UI: disabled ``` -क्लाउड सक्षम होने पर आवधिक सिंक `CloudSyncScheduler` द्वारा ट्रिगर किया जाता है। +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## डेटा मॉडल और स्टोरेज मैप +## Data Model and Storage Map -भौतिक भंडारण फ़ाइलें: +```mermaid +erDiagram + SETTINGS ||--o{ PROVIDER_CONNECTION : controls + PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider + PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage -- मुख्य स्थिति: `${DATA_DIR}/db.json` (या सेट होने पर `$XDG_CONFIG_HOME/omniroute/db.json`, अन्यथा `~/.omniroute/db.json`) -- उपयोग आँकड़े: `${DATA_DIR}/usage.json` -- अनुरोध लॉग लाइनें: `${DATA_DIR}/log.txt` -- वैकल्पिक अनुवादक/अनुरोध डिबग सत्र: `/logs/...` + SETTINGS { + boolean cloudEnabled + number stickyRoundRobinLimit + boolean requireLogin + string password_hash + string fallbackStrategy + json rateLimitDefaults + json providerProfiles + } -## परिनियोजन टोपोलॉजी + PROVIDER_CONNECTION { + string id + string provider + string authType + string name + number priority + boolean isActive + string apiKey + string accessToken + string refreshToken + string expiresAt + string testStatus + string lastError + string rateLimitedUntil + json providerSpecificData + } -## मॉड्यूल मैपिंग (निर्णय-महत्वपूर्ण) + PROVIDER_NODE { + string id + string type + string name + string prefix + string apiType + string baseUrl + } -### रूट और एपीआई मॉड्यूल + MODEL_ALIAS { + string alias + string targetModel + } -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: अनुकूलता एपीआई -- `src/app/api/v1/providers/[provider]/*`: प्रति-प्रदाता समर्पित मार्ग (चैट, एम्बेडिंग, चित्र) -- `src/app/api/providers*`: प्रदाता CRUD, सत्यापन, परीक्षण -- `src/app/api/provider-nodes*`: कस्टम संगत नोड प्रबंधन -- `src/app/api/provider-models`: कस्टम मॉडल प्रबंधन (CRUD) -- `src/app/api/models/catalog`: पूर्ण मॉडल कैटलॉग एपीआई (प्रदाता द्वारा समूहीकृत सभी प्रकार) -- `src/app/api/oauth/*`: OAuth/डिवाइस-कोड प्रवाह -- `src/app/api/keys*`: स्थानीय एपीआई कुंजी जीवनचक्र -- `src/app/api/models/alias`: उपनाम प्रबंधन -- `src/app/api/combos*`: फ़ॉलबैक कॉम्बो प्रबंधन -- `src/app/api/pricing`: लागत गणना के लिए मूल्य निर्धारण ओवरराइड होता है -- `src/app/api/settings/proxy`: प्रॉक्सी कॉन्फ़िगरेशन (प्राप्त/पुट/हटाएं) -- `src/app/api/settings/proxy/test`: आउटबाउंड प्रॉक्सी कनेक्टिविटी टेस्ट (POST) -- `src/app/api/usage/*`: एपीआई का उपयोग और लॉग -- `src/app/api/sync/*` + `src/app/api/cloud/*`: क्लाउड सिंक और क्लाउड-फेसिंग सहायक -- `src/app/api/cli-tools/*`: स्थानीय सीएलआई कॉन्फ़िगरेशन लेखक/चेकर्स -- `src/app/api/settings/ip-filter`: आईपी अनुमति सूची/ब्लॉकलिस्ट (प्राप्त/पुट) -- `src/app/api/settings/thinking-budget`: सोच टोकन बजट कॉन्फ़िगरेशन (प्राप्त/पुट) -- `src/app/api/settings/system-prompt`: ग्लोबल सिस्टम प्रॉम्प्ट (प्राप्त/पुट) -- `src/app/api/sessions`: सक्रिय सत्र सूची (प्राप्त करें) -- `src/app/api/rate-limits`: प्रति खाता दर सीमा स्थिति (GET) + COMBO { + string id + string name + string[] models + } -### रूटिंग और निष्पादन कोर + API_KEY { + string id + string name + string key + string machineId + } -- `src/sse/handlers/chat.ts`: अनुरोध पार्स, कॉम्बो हैंडलिंग, खाता चयन लूप -- `open-sse/handlers/chatCore.ts`: अनुवाद, निष्पादक प्रेषण, पुनः प्रयास/रीफ्रेश हैंडलिंग, स्ट्रीम सेटअप -- `open-sse/executors/*`: प्रदाता-विशिष्ट नेटवर्क और प्रारूप व्यवहार + USAGE_ENTRY { + string provider + string model + number prompt_tokens + number completion_tokens + string connectionId + string timestamp + } -### अनुवाद रजिस्ट्री और प्रारूप परिवर्तक + CUSTOM_MODEL { + string id + string name + string providerId + } -- `open-sse/translator/index.ts`: अनुवादक रजिस्ट्री और ऑर्केस्ट्रेशन -- अनुवादकों के लिए अनुरोध: `open-sse/translator/request/*` -- प्रतिक्रिया अनुवादक: `open-sse/translator/response/*` -- प्रारूप स्थिरांक: `open-sse/translator/formats.ts` + PROXY_CONFIG { + string global + json providers + } -### दृढ़ता + IP_FILTER { + string mode + string[] allowlist + string[] blocklist + } -- `src/lib/localDb.ts`: लगातार कॉन्फ़िगरेशन/स्थिति -- `src/lib/usageDb.ts`: उपयोग इतिहास और रोलिंग अनुरोध लॉग + THINKING_BUDGET { + string mode + number customBudget + string effortLevel + } -## प्रदाता निष्पादक कवरेज (रणनीति पैटर्न) + SYSTEM_PROMPT { + boolean enabled + string prompt + string position + } +``` -प्रत्येक प्रदाता के पास `BaseExecutor` (`open-sse/executors/base.ts` में) का विस्तार करने वाला एक विशेष निष्पादक होता है, जो URL निर्माण, हेडर निर्माण, घातीय बैकऑफ़ के साथ पुनः प्रयास, क्रेडेंशियल रिफ्रेश हुक और `execute()` ऑर्केस्ट्रेशन विधि प्रदान करता है। +Physical storage files: -| निष्पादक | प्रदाता(ओं) | विशेष हैंडलिंग | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| `DefaultExecutor` | ओपनएआई, क्लाउड, जेमिनी, क्वेन, आईफ्लो, ओपनराउटर, जीएलएम, किमी, मिनीमैक्स, डीपसीक, ग्रोक, एक्सएआई, मिस्ट्रल, पर्प्लेक्सिटी, टुगेदर, फायरवर्क्स, सेरेब्रा, कोहेरे, एनवीआईडीआईए | प्रति प्रदाता डायनामिक यूआरएल/हेडर कॉन्फिगरेशन | -| `AntigravityExecutor` | गूगल एंटीग्रेविटी | कस्टम प्रोजेक्ट/सत्र आईडी, पुनः प्रयास करें-पार्सिंग के बाद | -| `CodexExecutor` | ओपनएआई कोडेक्स | सिस्टम निर्देश इंजेक्ट करता है, तर्क करने का प्रयास करता है | -| `CursorExecutor` | कर्सर आईडीई | कनेक्टआरपीसी प्रोटोकॉल, प्रोटोबफ एन्कोडिंग, चेकसम के माध्यम से हस्ताक्षर करने का अनुरोध | -| `GithubExecutor` | गिटहब कोपायलट | कोपायलट टोकन ताज़ा करें, VSCode-नकल हेडर | -| `KiroExecutor` | एडब्ल्यूएस कोडव्हिस्परर/किरो | एडब्ल्यूएस इवेंटस्ट्रीम बाइनरी प्रारूप → एसएसई रूपांतरण | -| `GeminiCLIExecutor` | जेमिनी सीएलआई | Google OAuth टोकन ताज़ा चक्र | +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -अन्य सभी प्रदाता (कस्टम संगत नोड्स सहित) `DefaultExecutor` का उपयोग करते हैं। +## Deployment Topology -## प्रदाता संगतता मैट्रिक्स +```mermaid +flowchart LR + subgraph LocalHost[Developer Host] + CLI[CLI Tools] + Browser[Dashboard Browser] + end -| प्रदाता | प्रारूप | प्रामाणिक | स्ट्रीम | नॉन-स्ट्रीम | टोकन ताज़ा करें | उपयोग एपीआई | -| --------------------- | -------------------- | ------------------------ | ----------------- | ----------- | --------------- | ------------------- | -| क्लाउड | क्लाउड | एपीआई कुंजी / OAuth | ✅ | ✅ | ✅ | ⚠️ केवल एडमिन | -| मिथुन | मिथुन | एपीआई कुंजी / OAuth | ✅ | ✅ | ✅ | ⚠️ क्लाउड कंसोल | -| जेमिनी सीएलआई | मिथुन-क्ली | OAuth | ✅ | ✅ | ✅ | ⚠️ क्लाउड कंसोल | -| प्रतिगुरुत्वाकर्षण | प्रतिगुरुत्वाकर्षण | OAuth | ✅ | ✅ | ✅ | ✅ पूर्ण कोटा एपीआई | -| ओपनएआई | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| कोडेक्स | openai-प्रतिक्रियाएं | OAuth | ✅ मजबूर | ❌ | ✅ | ✅ दर सीमा | -| गिटहब कोपायलट | ओपनाई | OAuth + सहपायलट टोकन | ✅ | ✅ | ✅ | ✅ कोटा स्नैपशॉट | -| कर्सर | कर्सर | कस्टम चेकसम | ✅ | ✅ | ❌ | ❌ | -| किरो | किरो | एडब्ल्यूएस एसएसओ ओआईडीसी | ✅ (इवेंटस्ट्रीम) | ❌ | ✅ | ✅ उपयोग सीमा | -| क्वेन | ओपनाई | OAuth | ✅ | ✅ | ✅ | ⚠️ प्रति अनुरोध | -| आईफ्लो | ओपनाई | OAuth (बेसिक) | ✅ | ✅ | ✅ | ⚠️ प्रति अनुरोध | -| ओपनराउटर | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| जीएलएम/किमी/मिनीमैक्स | क्लाउड | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| डीपसीक | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| ग्रोक | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| एक्सएआई (ग्रोक) | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| मिस्ट्रल | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| उलझन | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| एक साथ एआई | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| आतिशबाजी एआई | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| सेरेब्रस | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| सहभागी | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | -| एनवीडिया एनआईएम | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | + subgraph ContainerOrProcess[OmniRoute Runtime] + Next[Next.js Server\nPORT=20128] + Core[SSE Core + Executors] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end -## प्रारूप अनुवाद कवरेज + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end -पता लगाए गए स्रोत प्रारूपों में शामिल हैं: + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | + +All other providers (including custom compatible nodes) use the `DefaultExecutor`. + +## Provider Compatibility Matrix + +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | + +## Format Translation Coverage + +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -लक्ष्य प्रारूपों में शामिल हैं: +Target formats include: -- ओपनएआई चैट/प्रतिक्रियाएं - -क्लाउड -- मिथुन/मिथुन-सीएलआई/एंटीग्रेविटी लिफाफा -- किरो -- कर्सर +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -अनुवाद **हब प्रारूप के रूप में ओपनएआई** का उपयोग करते हैं - सभी रूपांतरण मध्यवर्ती के रूप में ओपनएआई से गुजरते हैं: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -स्रोत पेलोड आकार और प्रदाता लक्ष्य प्रारूप के आधार पर अनुवादों का चयन गतिशील रूप से किया जाता है। +Translations are selected dynamically based on source payload shape and provider target format. -अनुवाद पाइपलाइन में अतिरिक्त प्रसंस्करण परतें: +Additional processing layers in the translation pipeline: -- **प्रतिक्रिया स्वच्छता** - सख्त एसडीके अनुपालन सुनिश्चित करने के लिए ओपनएआई-प्रारूप प्रतिक्रियाओं (स्ट्रीमिंग और गैर-स्ट्रीमिंग दोनों) से गैर-मानक फ़ील्ड हटा देता है -- **भूमिका सामान्यीकरण** - गैर-ओपनएआई लक्ष्यों के लिए `developer` → `system` परिवर्तित करता है; सिस्टम भूमिका को अस्वीकार करने वाले मॉडलों के लिए `system` → `user` का विलय (GLM, ERNIE) -- **टैग निष्कर्षण के बारे में सोचें** - पार्स `...` सामग्री को `reasoning_content` फ़ील्ड में ब्लॉक करता है -- **संरचित आउटपुट** - OpenAI `response_format.json_schema` को मिथुन के `responseMimeType` + `responseSchema` में परिवर्तित करता है +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## समर्थित एपीआई समापन बिंदु +## Supported API Endpoints -| समापन बिंदु | प्रारूप | हैंडलर | -| -------------------------------------------------- | -------------------- | -------------------------------------------------- | ------------------------ | -| `POST /v1/chat/completions` | ओपनएआई चैट | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | क्लाउड संदेश | वही हैंडलर (स्वतः पता चला) | -| `POST /v1/responses` | ओपनएआई प्रतिक्रियाएँ | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | ओपनएआई एंबेडिंग्स | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | मॉडल सूची | एपीआई मार्ग | -| `POST /v1/images/generations` | OpenAI छवियाँ | | -| `GET /v1/images/generations` | मॉडल सूची | एपीआई मार्ग | -| `POST /v1/providers/{provider}/chat/completions` | ओपनएआई चैट | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित | -| | ओपनएआई एंबेडिंग्स | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित | -| `POST /v1/providers/{provider}/images/generations` | OpenAI छवियाँ | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित | -| `POST /v1/messages/count_tokens` | क्लाउड टोकन गिनती | एपीआई मार्ग | -| | OpenAI मॉडल सूची | एपीआई मार्ग (चैट + एम्बेडिंग + छवि + कस्टम मॉडल) | -| `GET /api/models/catalog` | कैटलॉग | प्रदाता + प्रकार | द्वारा समूहीकृत सभी मॉडल | -| `POST /v1beta/models/*:streamGenerateContent` | मिथुन राशि के जातक | एपीआई मार्ग | -| | प्रॉक्सी कॉन्फिग | नेटवर्क प्रॉक्सी कॉन्फ़िगरेशन | -| | प्रॉक्सी कनेक्टिविटी | प्रॉक्सी स्वास्थ्य/कनेक्टिविटी परीक्षण समापन बिंदु | -| | कस्टम मॉडल | प्रति प्रदाता कस्टम मॉडल प्रबंधन | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## बायपास हैंडलर +## Bypass Handler -बाईपास हैंडलर (`open-sse/utils/bypassHandler.ts`) क्लाउड सीएलआई से ज्ञात "थ्रोअवे" अनुरोधों को रोकता है - वार्मअप पिंग, शीर्षक निष्कर्षण, और टोकन गिनती - और अपस्ट्रीम प्रदाता टोकन का उपभोग किए बिना **नकली प्रतिक्रिया** लौटाता है। यह तभी ट्रिगर होता है जब `User-Agent` में `claude-cli` होता है। +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## लॉगर पाइपलाइन का अनुरोध करें +## Request Logger Pipeline -अनुरोध लकड़हारा (`open-sse/utils/requestLogger.ts`) एक 7-चरण डीबग लॉगिंग पाइपलाइन प्रदान करता है, जो डिफ़ॉल्ट रूप से अक्षम है, `ENABLE_REQUEST_LOGS=true` के माध्यम से सक्षम है: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: -प्रत्येक अनुरोध सत्र के लिए फ़ाइलें `/logs//` पर लिखी जाती हैं। +``` +1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json +→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt +``` -## विफलता के तरीके और लचीलापन +Files are written to `/logs//` for each request session. -## 1) खाता/प्रदाता उपलब्धता +## Failure Modes and Resilience -- क्षणिक/दर/प्रामाणिक त्रुटियों पर प्रदाता खाता ठंडा हो गया -- अनुरोध विफल होने से पहले खाता फ़ॉलबैक -- वर्तमान मॉडल/प्रदाता पथ समाप्त होने पर कॉम्बो मॉडल फ़ॉलबैक +## 1) Account/Provider Availability -## 2) टोकन समाप्ति +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -- ताज़ा करने योग्य प्रदाताओं के लिए पुनः प्रयास के साथ पूर्व-जांच और ताज़ा करें -- कोर पथ में ताज़ा प्रयास के बाद 401/403 पुनः प्रयास करें +## 2) Token Expiry -## 3) स्ट्रीम सुरक्षा +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -- डिस्कनेक्ट-अवेयर स्ट्रीम नियंत्रक -- एंड-ऑफ-स्ट्रीम फ्लश और `[DONE]` हैंडलिंग के साथ अनुवाद स्ट्रीम -- प्रदाता उपयोग मेटाडेटा अनुपलब्ध होने पर उपयोग अनुमान फ़ॉलबैक +## 3) Stream Safety -## 4) क्लाउड सिंक गिरावट +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -- समन्वयन त्रुटियाँ सामने आती हैं लेकिन स्थानीय रनटाइम जारी रहता है -- शेड्यूलर में पुनः प्रयास-सक्षम तर्क है, लेकिन आवधिक निष्पादन वर्तमान में डिफ़ॉल्ट रूप से एकल-प्रयास सिंक को कॉल करता है +## 4) Cloud Sync Degradation -## 5) डेटा इंटीग्रिटी +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -- गुम चाबियों के लिए डीबी आकार माइग्रेशन/मरम्मत -- लोकलडीबी और यूज़डीबी के लिए भ्रष्ट JSON रीसेट सुरक्षा उपाय +## 5) Data Integrity -## अवलोकनशीलता और परिचालन संकेत +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -रनटाइम दृश्यता स्रोत: +## Observability and Operational Signals -- `src/sse/utils/logger.ts` से कंसोल लॉग -- `usage.json` में प्रति-अनुरोध उपयोग समुच्चय -- पाठ्य अनुरोध स्थिति लॉग इन `log.txt` -- `logs/` के अंतर्गत वैकल्पिक गहन अनुरोध/अनुवाद लॉग जब `ENABLE_REQUEST_LOGS=true` -- यूआई खपत के लिए डैशबोर्ड उपयोग समापन बिंदु (`/api/usage/*`)। +Runtime visibility sources: -## सुरक्षा-संवेदनशील सीमाएँ +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -- JWT सीक्रेट (`JWT_SECRET`) डैशबोर्ड सत्र कुकी सत्यापन/हस्ताक्षर को सुरक्षित करता है -- प्रारंभिक पासवर्ड फ़ॉलबैक (`INITIAL_PASSWORD`, डिफ़ॉल्ट `123456`) को वास्तविक परिनियोजन में ओवरराइड किया जाना चाहिए -- एपीआई कुंजी एचएमएसी रहस्य (`API_KEY_SECRET`) उत्पन्न स्थानीय एपीआई कुंजी प्रारूप को सुरक्षित करता है -- प्रदाता रहस्य (एपीआई कुंजी/टोकन) स्थानीय डीबी में बने रहते हैं और उन्हें फ़ाइल सिस्टम स्तर पर संरक्षित किया जाना चाहिए -- क्लाउड सिंक एंडपॉइंट एपीआई कुंजी ऑथ + मशीन आईडी सेमेन्टिक्स पर निर्भर करते हैं +## Security-Sensitive Boundaries -## पर्यावरण और रनटाइम मैट्रिक्स +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -कोड द्वारा सक्रिय रूप से उपयोग किए जाने वाले पर्यावरण चर: +## Environment and Runtime Matrix -- ऐप/ऑथ: `JWT_SECRET`, `INITIAL_PASSWORD` -- भंडारण: `DATA_DIR` -- संगत नोड व्यवहार: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- वैकल्पिक स्टोरेज बेस ओवरराइड (लिनक्स/मैकओएस जब `DATA_DIR` सेट न हो): `XDG_CONFIG_HOME` -- सुरक्षा हैशिंग: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- लॉगिंग: `ENABLE_REQUEST_LOGS` -- सिंक/क्लाउड यूआरएल: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- आउटबाउंड प्रॉक्सी: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` और लोअरकेस वेरिएंट -- SOCKS5 फ़ीचर फ़्लैग: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- प्लेटफ़ॉर्म/रनटाइम सहायक (ऐप-विशिष्ट कॉन्फ़िगरेशन नहीं): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +Environment variables actively used by code: -## ज्ञात वास्तुशिल्प नोट्स +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -1. `usageDb` और `localDb` अब लीगेसी फ़ाइल माइग्रेशन के साथ समान आधार निर्देशिका नीति (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) साझा करते हैं। -2. `/api/v1/route.ts` एक स्थिर मॉडल सूची लौटाता है और यह `/v1/models` द्वारा उपयोग किया जाने वाला मुख्य मॉडल स्रोत नहीं है। -3. अनुरोध लकड़हारा सक्षम होने पर पूर्ण हेडर/बॉडी लिखता है; लॉग निर्देशिका को संवेदनशील मानें। -4. क्लाउड व्यवहार सही `NEXT_PUBLIC_BASE_URL` और क्लाउड एंडपॉइंट रीचैबिलिटी पर निर्भर करता है। -5. `open-sse/` निर्देशिका को `@omniroute/open-sse` **npm कार्यक्षेत्र पैकेज** के रूप में प्रकाशित किया गया है। स्रोत कोड इसे `@omniroute/open-sse/...` के माध्यम से आयात करता है (Next.js `transpilePackages` द्वारा हल किया गया)। इस दस्तावेज़ में फ़ाइल पथ अभी भी स्थिरता के लिए निर्देशिका नाम `open-sse/` का उपयोग करते हैं। -6. डैशबोर्ड में चार्ट सुलभ, इंटरैक्टिव एनालिटिक्स विज़ुअलाइज़ेशन (मॉडल उपयोग बार चार्ट, सफलता दर के साथ प्रदाता ब्रेकडाउन टेबल) के लिए **रिचार्ट्स** (एसवीजी-आधारित) का उपयोग करते हैं। -7. E2E परीक्षण **Playwright** (`tests/e2e/`) का उपयोग करते हैं, `npm run test:e2e` के माध्यम से चलते हैं। यूनिट परीक्षण **Node.js टेस्ट रनर** (`tests/unit/`) का उपयोग करते हैं, जो `npm run test:plan3` के माध्यम से चलते हैं। `src/` के अंतर्गत स्रोत कोड **टाइपस्क्रिप्ट** (`.ts`/`.tsx`) है; `open-sse/` कार्यस्थान जावास्क्रिप्ट (`.js`) बना हुआ है। -8. सेटिंग्स पृष्ठ को 5 टैब में व्यवस्थित किया गया है: सुरक्षा, रूटिंग (6 वैश्विक रणनीतियाँ: भरण-प्रथम, राउंड-रॉबिन, पी2सी, यादृच्छिक, कम से कम उपयोग किया गया, लागत-अनुकूलित), लचीलापन (संपादन योग्य दर सीमा, सर्किट ब्रेकर, नीतियां), एआई (सोच बजट, सिस्टम प्रॉम्प्ट, प्रॉम्प्ट कैश), उन्नत (प्रॉक्सी)। +## Known Architectural Notes -## परिचालन सत्यापन चेकलिस्ट +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -- स्रोत से निर्मित: `npm run build` -- डॉकर छवि बनाएं: `docker build -t omniroute .` -- सेवा प्रारंभ करें और सत्यापित करें: +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- जब `PORT=20128` हो तो CLI लक्ष्य आधार URL `http://:20128/v1` होना चाहिए +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/in/CODEBASE_DOCUMENTATION.md b/docs/i18n/in/CODEBASE_DOCUMENTATION.md index 4c6d82a088..303880c198 100644 --- a/docs/i18n/in/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/in/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute - कोडबेस दस्तावेज़ीकरण +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> **ओम्नीरूटे** मल्टी-प्रोवाइडर एआई प्रॉक्सी राउटर के लिए एक व्यापक, शुरुआती-अनुकूल मार्गदर्शिका। +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. सर्वव्यापी क्या है? +## 1. What Is omniroute? -ऑम्नीरूट एक **प्रॉक्सी राउटर** है जो एआई क्लाइंट (क्लाउड सीएलआई, कोडेक्स, कर्सर आईडीई, आदि) और एआई प्रदाताओं (एंथ्रोपिक, गूगल, ओपनएआई, एडब्ल्यूएस, गिटहब, आदि) के बीच बैठता है। यह एक बड़ी समस्या का समाधान करता है: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **अलग-अलग एआई क्लाइंट अलग-अलग "भाषाएं" (एपीआई प्रारूप) बोलते हैं, और अलग-अलग एआई प्रदाता भी अलग-अलग "भाषाओं" की अपेक्षा करते हैं।** ऑम्नीरूट स्वचालित रूप से उनके बीच अनुवाद करता है। +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -इसे संयुक्त राष्ट्र में एक सार्वभौमिक अनुवादक की तरह समझें - कोई भी प्रतिनिधि कोई भी भाषा बोल सकता है, और अनुवादक इसे किसी अन्य प्रतिनिधि के लिए परिवर्तित कर देता है। +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. वास्तुकला अवलोकन +## 2. Architecture Overview ```mermaid graph LR @@ -61,15 +61,20 @@ graph LR H -.-> G ``` -### मुख्य सिद्धांत: हब-एंड-स्पोक अनुवाद +### Core Principle: Hub-and-Spoke Translation -सभी प्रारूप अनुवाद **हब के रूप में ओपनएआई प्रारूप** से होकर गुजरता है: +All format translation passes through **OpenAI format as the hub**: -इसका मतलब है कि आपको **N²** (प्रत्येक जोड़ी) के बजाय केवल **N अनुवादकों** (प्रति प्रारूप एक) की आवश्यकता है। +``` +Client Format → [OpenAI Hub] → Provider Format (request) +Provider Format → [OpenAI Hub] → Client Format (response) +``` + +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. परियोजना संरचना +## 3. Project Structure ``` omniroute/ @@ -99,22 +104,22 @@ omniroute/ --- -## 4. मॉड्यूल-दर-मॉड्यूल ब्रेकडाउन +## 4. Module-by-Module Breakdown -### 4.1 कॉन्फ़िगरेशन (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -सभी प्रदाता कॉन्फ़िगरेशन के लिए **सत्य का एकल स्रोत**। +The **single source of truth** for all provider configuration. -| फ़ाइल | उद्देश्य | -| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` प्रत्येक प्रदाता के लिए आधार URL, OAuth क्रेडेंशियल (डिफ़ॉल्ट), हेडर और डिफ़ॉल्ट सिस्टम संकेतों के साथ ऑब्जेक्ट। `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, और `SKIP_PATTERNS` को भी परिभाषित करता है। | -| `credentialLoader.ts` | `data/provider-credentials.json` से बाहरी क्रेडेंशियल लोड करता है और उन्हें `PROVIDERS` में हार्डकोडेड डिफ़ॉल्ट पर मर्ज करता है। पश्चगामी संगतता बनाए रखते हुए रहस्यों को स्रोत नियंत्रण से बाहर रखता है। | -| `providerModels.ts` | केंद्रीय मॉडल रजिस्ट्री: मानचित्र प्रदाता उपनाम → मॉडल आईडी। `getModels()`, `getProviderByAlias()` जैसे कार्य। | -| `codexInstructions.ts` | सिस्टम निर्देश कोडेक्स अनुरोधों (संपादन बाधाएं, सैंडबॉक्स नियम, अनुमोदन नीतियां) में शामिल किए गए हैं। | -| `defaultThinkingSignature.ts` | क्लाउड और जेमिनी मॉडल के लिए डिफ़ॉल्ट "सोच" हस्ताक्षर। | -| `ollamaModels.ts` | स्थानीय ओलामा मॉडल के लिए स्कीमा परिभाषा (नाम, आकार, परिवार, परिमाणीकरण)। | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### क्रेडेंशियल लोडिंग फ़्लो +#### Credential Loading Flow ```mermaid flowchart TD @@ -137,9 +142,9 @@ flowchart TD --- -### 4.2 निष्पादक (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -निष्पादक **रणनीति पैटर्न** का उपयोग करके **प्रदाता-विशिष्ट तर्क** को समाहित करते हैं। प्रत्येक निष्पादक आवश्यकतानुसार आधार विधियों को ओवरराइड करता है। +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -189,59 +194,113 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| निष्पादक | प्रदाता | प्रमुख विशेषज्ञताएं | -| ---------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | सार आधार: यूआरएल निर्माण, हेडर, पुनः प्रयास तर्क, क्रेडेंशियल ताज़ा | -| `default.ts` | क्लाउड, जेमिनी, ओपनएआई, जीएलएम, किमी, मिनीमैक्स | मानक प्रदाताओं के लिए जेनेरिक OAuth टोकन ताज़ा करें | -| `antigravity.ts` | गूगल क्लाउड कोड | प्रोजेक्ट/सत्र आईडी जनरेशन, मल्टी-यूआरएल फ़ॉलबैक, त्रुटि संदेशों से कस्टम पुनः प्रयास पार्सिंग ("2h7m23s के बाद रीसेट करें") | -| `cursor.ts` | कर्सर आईडीई | **सबसे जटिल**: SHA-256 चेकसम ऑथ, प्रोटोबफ अनुरोध एन्कोडिंग, बाइनरी इवेंटस्ट्रीम → SSE प्रतिक्रिया पार्सिंग | -| `codex.ts` | ओपनएआई कोडेक्स | सिस्टम निर्देशों को इंजेक्ट करता है, सोच के स्तर को प्रबंधित करता है, असमर्थित मापदंडों को हटाता है | -| `gemini-cli.ts` | गूगल जेमिनी सीएलआई | कस्टम यूआरएल बिल्डिंग (`streamGenerateContent`), Google OAuth टोकन रिफ्रेश | -| `github.ts` | गिटहब कोपायलट | दोहरी टोकन प्रणाली (GitHub OAuth + Copilot टोकन), VSCode हेडर की नकल | -| `kiro.ts` | एडब्ल्यूएस कोडव्हिस्परर | एडब्ल्यूएस इवेंटस्ट्रीम बाइनरी पार्सिंग, एएमजेडएन इवेंट फ्रेम, टोकन अनुमान | -| `index.ts` | — | फ़ैक्टरी: मानचित्र प्रदाता का नाम → निष्पादक वर्ग, डिफ़ॉल्ट फ़ॉलबैक के साथ | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 हैंडलर (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**ऑर्केस्ट्रेशन परत** - अनुवाद, निष्पादन, स्ट्रीमिंग और त्रुटि प्रबंधन का समन्वय करती है। +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| फ़ाइल | उद्देश्य | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `chatCore.ts` | **केंद्रीय ऑर्केस्ट्रेटर** (~600 पंक्तियाँ)। संपूर्ण अनुरोध जीवनचक्र को संभालता है: प्रारूप का पता लगाना → अनुवाद → निष्पादक प्रेषण → स्ट्रीमिंग/गैर-स्ट्रीमिंग प्रतिक्रिया → टोकन ताज़ा करना → त्रुटि प्रबंधन → उपयोग लॉगिंग। | -| `responsesHandler.ts` | OpenAI के रिस्पॉन्स एपीआई के लिए एडाप्टर: रिस्पॉन्स फॉर्मेट को कनवर्ट करता है → चैट कंप्लीटेशन → `chatCore` को भेजता है → SSE को रिस्पॉन्स फॉर्मेट में वापस कनवर्ट करता है। | -| `embeddings.ts` | एंबेडिंग जेनरेशन हैंडलर: एंबेडिंग मॉडल → प्रदाता को हल करता है, प्रदाता एपीआई को भेजता है, ओपनएआई-संगत एंबेडिंग प्रतिक्रिया देता है। 6+ प्रदाताओं का समर्थन करता है। | -| `imageGeneration.ts` | छवि निर्माण हैंडलर: छवि मॉडल → प्रदाता को हल करता है, ओपनएआई-संगत, जेमिनी-छवि (एंटीग्रेविटी), और फ़ॉलबैक (नेबियस) मोड का समर्थन करता है। बेस64 या यूआरएल छवियाँ लौटाता है। | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### अनुरोध जीवनचक्र (chatCore.ts) +#### Request Lifecycle (chatCore.ts) + +```mermaid +sequenceDiagram + participant Client + participant chatCore + participant Translator + participant Executor + participant Provider + + Client->>chatCore: Request (any format) + chatCore->>chatCore: Detect source format + chatCore->>chatCore: Check bypass patterns + chatCore->>chatCore: Resolve model & provider + chatCore->>Translator: Translate request (source → OpenAI → target) + chatCore->>Executor: Get executor for provider + Executor->>Executor: Build URL, headers, transform request + Executor->>Executor: Refresh credentials if needed + Executor->>Provider: HTTP fetch (streaming or non-streaming) + + alt Streaming + Provider-->>chatCore: SSE stream + chatCore->>chatCore: Pipe through SSE transform stream + Note over chatCore: Transform stream translates
each chunk: target → OpenAI → source + chatCore-->>Client: Translated SSE stream + else Non-streaming + Provider-->>chatCore: JSON response + chatCore->>Translator: Translate response + chatCore-->>Client: Translated JSON + end + + alt Error (401, 429, 500...) + chatCore->>Executor: Retry with credential refresh + chatCore->>chatCore: Account fallback logic + end +``` --- -### 4.4 सेवाएँ (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -व्यावसायिक तर्क जो संचालकों और निष्पादकों का समर्थन करता है। +Business logic that supports the handlers and executors. -| फ़ाइल | उद्देश्य | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **प्रारूप का पता लगाना** (`detectFormat`): क्लॉड/ओपनएआई/जेमिनी/एंटीग्रेविटी/प्रतिक्रिया प्रारूपों की पहचान करने के लिए अनुरोध बॉडी संरचना का विश्लेषण करता है (क्लाउड के लिए `max_tokens` अनुमान शामिल है)। इसके अलावा: यूआरएल बिल्डिंग, हेडर बिल्डिंग, थिंकिंग कॉन्फिग सामान्यीकरण। `openai-compatible-*` और `anthropic-compatible-*` गतिशील प्रदाताओं का समर्थन करता है। | -| `model.ts` | मॉडल स्ट्रिंग पार्सिंग (`claude/model-name` → `{provider: "claude", model: "model-name"}`), टकराव का पता लगाने के साथ उपनाम रिज़ॉल्यूशन, इनपुट सैनिटाइजेशन (पथ ट्रैवर्सल/नियंत्रण वर्ण को अस्वीकार करता है), और एसिंक उपनाम गेटर समर्थन के साथ मॉडल जानकारी रिज़ॉल्यूशन। | -| `accountFallback.ts` | दर-सीमा प्रबंधन: घातीय बैकऑफ़ (1s → 2s → 4s → अधिकतम 2 मिनट), खाता कूल्डाउन प्रबंधन, त्रुटि वर्गीकरण (कौन सी त्रुटियाँ फ़ॉलबैक को ट्रिगर करती हैं बनाम नहीं)। | -| `tokenRefresh.ts` | **प्रत्येक प्रदाता** के लिए OAuth टोकन ताज़ा करें: Google (मिथुन, एंटीग्रेविटी), क्लाउड, कोडेक्स, क्वेन, iFlow, GitHub (OAuth + Copilot डुअल-टोकन), किरो (AWS SSO OIDC + सोशल ऑथ)। इसमें इन-फ़्लाइट प्रॉमिस डिडुप्लीकेशन कैश और एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास शामिल है। | -| `combo.ts` | **कॉम्बो मॉडल**: फ़ॉलबैक मॉडल की श्रृंखलाएँ। यदि मॉडल ए फ़ॉलबैक-योग्य त्रुटि के साथ विफल हो जाता है, तो मॉडल बी, फिर सी, आदि का प्रयास करें। वास्तविक अपस्ट्रीम स्थिति कोड लौटाता है। | -| `usage.ts` | प्रदाता एपीआई (गिटहब कोपायलट कोटा, एंटीग्रेविटी मॉडल कोटा, कोडेक्स दर सीमा, किरो उपयोग ब्रेकडाउन, क्लाउड सेटिंग्स) से कोटा/उपयोग डेटा प्राप्त करता है। | -| `accountSelector.ts` | स्कोरिंग एल्गोरिदम के साथ स्मार्ट खाता चयन: प्रत्येक अनुरोध के लिए इष्टतम खाता चुनने के लिए प्राथमिकता, स्वास्थ्य स्थिति, राउंड-रॉबिन स्थिति और कूलडाउन स्थिति पर विचार करता है। | -| `contextManager.ts` | अनुरोध संदर्भ जीवनचक्र प्रबंधन: डिबगिंग और लॉगिंग के लिए मेटाडेटा (अनुरोध आईडी, टाइमस्टैम्प, प्रदाता जानकारी) के साथ प्रति-अनुरोध संदर्भ ऑब्जेक्ट बनाता है और ट्रैक करता है। | -| `ipFilter.ts` | आईपी-आधारित अभिगम नियंत्रण: अनुमति सूची और ब्लॉकलिस्ट मोड का समर्थन करता है। एपीआई अनुरोधों को संसाधित करने से पहले कॉन्फ़िगर किए गए नियमों के विरुद्ध क्लाइंट आईपी को सत्यापित करता है। | -| `sessionManager.ts` | क्लाइंट फ़िंगरप्रिंटिंग के साथ सत्र ट्रैकिंग: हैश किए गए क्लाइंट पहचानकर्ताओं का उपयोग करके सक्रिय सत्रों को ट्रैक करता है, अनुरोधों की संख्या पर नज़र रखता है, और सत्र मेट्रिक्स प्रदान करता है। | -| `signatureCache.ts` | अनुरोध हस्ताक्षर-आधारित डिडुप्लीकेशन कैश: हाल के अनुरोध हस्ताक्षरों को कैश करके और एक समय विंडो के भीतर समान अनुरोधों के लिए कैश्ड प्रतिक्रियाओं को लौटाकर डुप्लिकेट अनुरोधों को रोकता है। | -| `systemPrompt.ts` | वैश्विक सिस्टम प्रॉम्प्ट इंजेक्शन: प्रति-प्रदाता संगतता प्रबंधन के साथ, सभी अनुरोधों के लिए एक कॉन्फ़िगर करने योग्य सिस्टम प्रॉम्प्ट को जोड़ता या जोड़ता है। | -| `thinkingBudget.ts` | रीज़निंग टोकन बजट प्रबंधन: सोच/तर्क टोकन को नियंत्रित करने के लिए पासथ्रू, ऑटो (स्ट्रिप थिंकिंग कॉन्फ़िगरेशन), कस्टम (निश्चित बजट), और अनुकूली (जटिलता-स्केल) मोड का समर्थन करता है। | -| `wildcardRouter.ts` | वाइल्डकार्ड मॉडल पैटर्न रूटिंग: उपलब्धता और प्राथमिकता के आधार पर वाइल्डकार्ड पैटर्न (उदाहरण के लिए, `*/claude-*`) को ठोस प्रदाता/मॉडल जोड़े में हल करता है। | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### टोकन रिफ्रेश डिडुप्लीकेशन +#### Token Refresh Deduplication -#### खाता फ़ॉलबैक स्टेट मशीन +```mermaid +sequenceDiagram + participant R1 as Request 1 + participant R2 as Request 2 + participant Cache as refreshPromiseCache + participant OAuth as OAuth Provider + + R1->>Cache: getAccessToken("gemini", token) + Cache->>Cache: No in-flight promise + Cache->>OAuth: Start refresh + R2->>Cache: getAccessToken("gemini", token) + Cache->>Cache: Found in-flight promise + Cache-->>R2: Return existing promise + OAuth-->>Cache: New access token + Cache-->>R1: New access token + Cache-->>R2: Same access token (shared) + Cache->>Cache: Delete cache entry +``` + +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -266,15 +325,30 @@ stateDiagram-v2 } ``` -#### कॉम्बो मॉडल श्रृंखला +#### Combo Model Chain + +```mermaid +flowchart LR + A["Request with\ncombo model"] --> B["Model A"] + B -->|"2xx Success"| C["Return response"] + B -->|"429/401/500"| D{"Fallback\neligible?"} + D -->|Yes| E["Model B"] + D -->|No| F["Return error"] + E -->|"2xx Success"| C + E -->|"429/401/500"| G{"Fallback\neligible?"} + G -->|Yes| H["Model C"] + G -->|No| F + H -->|"2xx Success"| C + H -->|"Fail"| I["All failed →\nReturn last status"] +``` --- -### 4.5 अनुवादक (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -स्व-पंजीकरण प्लगइन सिस्टम का उपयोग करके **प्रारूप अनुवाद इंजन**। +The **format translation engine** using a self-registering plugin system. -#### वास्तुकला +#### Architecture ```mermaid graph TD @@ -300,15 +374,15 @@ graph TD end ``` -| निर्देशिका | फ़ाइलें | विवरण | -| ----------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 अनुवादक | प्रारूपों के बीच अनुरोध निकायों को परिवर्तित करें। प्रत्येक फ़ाइल आयात पर `register(from, to, fn)` के माध्यम से स्व-पंजीकृत होती है। | -| `response/` | 7 अनुवादक | प्रारूपों के बीच स्ट्रीमिंग प्रतिक्रिया खंडों को परिवर्तित करें। एसएसई इवेंट प्रकार, थिंकिंग ब्लॉक, टूल कॉल को संभालता है। | -| `helpers/` | 6 सहायक | साझा उपयोगिताएँ: `claudeHelper` (सिस्टम प्रॉम्प्ट निष्कर्षण, सोच कॉन्फ़िगरेशन), `geminiHelper` (भाग/सामग्री मैपिंग), `openaiHelper` (प्रारूप फ़िल्टरिंग), `toolCallHelper` (आईडी जनरेशन, अनुपलब्ध प्रतिक्रिया इंजेक्शन), `maxTokensHelper`, `responsesApiHelper`। | -| `index.ts` | — | अनुवाद इंजन: `translateRequest()`, `translateResponse()`, राज्य प्रबंधन, रजिस्ट्री। | -| | — | प्रारूप स्थिरांक: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`। | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### मुख्य डिज़ाइन: स्व-पंजीकरण प्लगइन्स +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -321,128 +395,195 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 उपयोगिताएँ (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| फ़ाइल | उद्देश्य | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | त्रुटि प्रतिक्रिया निर्माण (ओपनएआई-संगत प्रारूप), अपस्ट्रीम त्रुटि पार्सिंग, त्रुटि संदेशों से एंटीग्रेविटी रिट्री-टाइम निष्कर्षण, एसएसई त्रुटि स्ट्रीमिंग। | -| `stream.ts` | **एसएसई ट्रांसफॉर्म स्ट्रीम** - कोर स्ट्रीमिंग पाइपलाइन। दो मोड: `TRANSLATE` (पूर्ण प्रारूप अनुवाद) और `PASSTHROUGH` (सामान्यीकरण + उपयोग निकालें)। चंक बफ़रिंग, उपयोग अनुमान, सामग्री लंबाई ट्रैकिंग को संभालता है। प्रति-स्ट्रीम एनकोडर/डिकोडर उदाहरण साझा स्थिति से बचते हैं। | -| `streamHelpers.ts` | निम्न-स्तरीय SSE उपयोगिताएँ: `parseSSELine` (व्हाट्सएप-सहिष्णु), `hasValuableContent` (OpenAI/क्लाउड/जेमिनी के लिए खाली हिस्सों को फ़िल्टर करता है), `fixInvalidId`, `formatSSE` (`perf_metrics` क्लीनअप के साथ प्रारूप-जागरूक SSE क्रमबद्धता)। | -| `usageTracking.ts` | किसी भी प्रारूप से टोकन उपयोग निष्कर्षण (क्लाउड/ओपनएआई/मिथुन/प्रतिक्रियाएं), अलग टूल/संदेश चार-प्रति-टोकन अनुपात के साथ अनुमान, बफर जोड़ (2000 टोकन सुरक्षा मार्जिन), प्रारूप-विशिष्ट फ़ील्ड फ़िल्टरिंग, एएनएसआई रंगों के साथ कंसोल लॉगिंग। | -| `requestLogger.ts` | फ़ाइल-आधारित अनुरोध लॉगिंग (`ENABLE_REQUEST_LOGS=true` के माध्यम से ऑप्ट-इन)। क्रमांकित फ़ाइलों के साथ सत्र फ़ोल्डर बनाता है: `1_req_client.json` → `7_res_client.txt`। सभी I/O async (दाग-और-भूल) है। संवेदनशील हेडर को छुपाता है. | -| `bypassHandler.ts` | क्लाउड सीएलआई (शीर्षक निष्कर्षण, वार्मअप, गिनती) से विशिष्ट पैटर्न को रोकता है और किसी भी प्रदाता को कॉल किए बिना नकली प्रतिक्रियाएं लौटाता है। स्ट्रीमिंग और नॉन-स्ट्रीमिंग दोनों का समर्थन करता है। जानबूझकर क्लाउड सीएलआई दायरे तक सीमित। | -| `networkProxy.ts` | किसी दिए गए प्रदाता के लिए आउटबाउंड प्रॉक्सी URL को प्राथमिकता के साथ हल करता है: प्रदाता-विशिष्ट कॉन्फ़िगरेशन → वैश्विक कॉन्फ़िगरेशन → पर्यावरण चर (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`)। `NO_PROXY` बहिष्करण का समर्थन करता है। 30 के दशक के लिए कैश कॉन्फिगरेशन। | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### एसएसई स्ट्रीमिंग पाइपलाइन +#### SSE Streaming Pipeline -#### लॉगर सत्र संरचना का अनुरोध करें +```mermaid +flowchart TD + A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"] + B --> C["Buffer lines\n(split on newline)"] + C --> D["parseSSELine()\n(trim whitespace, parse JSON)"] + D --> E{"Mode?"} + E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"] + E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"] + F --> H["hasValuableContent()\nfilter empty chunks"] + G --> H + H -->|"Has content"| I["extractUsage()\ntrack token counts"] + H -->|"Empty"| J["Skip chunk"] + I --> K["formatSSE()\nserialize + clean perf_metrics"] + K --> L["TextEncoder\n(per-stream instance)"] + L --> M["Enqueue to\nclient stream"] + + style A fill:#f9f,stroke:#333 + style M fill:#9f9,stroke:#333 +``` + +#### Request Logger Session Structure + +``` +logs/ +└── claude_gemini_claude-sonnet_20260208_143045/ + ├── 1_req_client.json ← Raw client request + ├── 2_req_source.json ← After initial conversion + ├── 3_req_openai.json ← OpenAI intermediate format + ├── 4_req_target.json ← Final target format + ├── 5_res_provider.txt ← Provider SSE chunks (streaming) + ├── 5_res_provider.json ← Provider response (non-streaming) + ├── 6_res_openai.txt ← OpenAI intermediate chunks + ├── 7_res_client.txt ← Client-facing SSE chunks + └── 6_error.json ← Error details (if any) +``` --- -### 4.7 अनुप्रयोग परत (`src/`) +### 4.7 Application Layer (`src/`) -| निर्देशिका | उद्देश्य | -| ------------- | ------------------------------------------------------------------------------- | -| `src/app/` | वेब यूआई, एपीआई रूट, एक्सप्रेस मिडलवेयर, ओएथ कॉलबैक हैंडलर | -| `src/lib/` | डेटाबेस एक्सेस (`localDb.ts`, `usageDb.ts`), प्रमाणीकरण, साझा | -| `src/mitm/` | प्रदाता ट्रैफ़िक को रोकने के लिए मैन-इन-द-मिडिल प्रॉक्सी उपयोगिताएँ | -| `src/models/` | डेटाबेस मॉडल परिभाषाएँ | -| `src/shared/` | ओपन-एसएसई फ़ंक्शंस (प्रदाता, स्ट्रीम, त्रुटि, आदि) के आसपास रैपर | -| `src/sse/` | एसएसई एंडपॉइंट हैंडलर जो ओपन-एसएसई लाइब्रेरी को एक्सप्रेस मार्गों से जोड़ते हैं | -| `src/store/` | आवेदन राज्य प्रबंधन | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### उल्लेखनीय एपीआई रूट +#### Notable API Routes -| मार्ग | तरीके | उद्देश्य | -| --------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------- | -| `/api/provider-models` | प्राप्त करें/पोस्ट करें/हटाएं | प्रति प्रदाता कस्टम मॉडल के लिए सीआरयूडी | -| `/api/models/catalog` | प्राप्त करें | प्रदाता द्वारा समूहीकृत सभी मॉडलों (चैट, एम्बेडिंग, छवि, कस्टम) की एकत्रित सूची | -| `/api/settings/proxy` | प्राप्त/पुट/डिलीट | पदानुक्रमित आउटबाउंड प्रॉक्सी कॉन्फ़िगरेशन (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | पोस्ट | प्रॉक्सी कनेक्टिविटी को सत्यापित करता है और सार्वजनिक आईपी/विलंबता लौटाता है | -| `/v1/providers/[provider]/chat/completions` | पोस्ट | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित चैट पूर्णताएँ | -| `/v1/providers/[provider]/embeddings` | पोस्ट | मॉडल सत्यापन के साथ समर्पित प्रति-प्रदाता एम्बेडिंग | -| `/v1/providers/[provider]/images/generations` | पोस्ट | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित छवि निर्माण | -| `/api/settings/ip-filter` | प्राप्त/डालें | आईपी ​​अनुमति सूची/अवरुद्ध सूची प्रबंधन | -| `/api/settings/thinking-budget` | प्राप्त/डालें | रीज़निंग टोकन बजट कॉन्फ़िगरेशन (पासथ्रू/ऑटो/कस्टम/अनुकूली) | -| `/api/settings/system-prompt` | प्राप्त/डालें | सभी अनुरोधों के लिए वैश्विक सिस्टम प्रॉम्प्ट इंजेक्शन | -| `/api/sessions` | प्राप्त करें | सक्रिय सत्र ट्रैकिंग और मेट्रिक्स | -| `/api/rate-limits` | प्राप्त करें | प्रति खाता दर सीमा स्थिति | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. मुख्य डिज़ाइन पैटर्न +## 5. Key Design Patterns -### 5.1 हब-एंड-स्पोक अनुवाद +### 5.1 Hub-and-Spoke Translation -सभी प्रारूप **हब के रूप में ओपनएआई प्रारूप** के माध्यम से अनुवादित होते हैं। एक नया प्रदाता जोड़ने के लिए केवल अनुवादकों की **एक जोड़ी** (OpenAI से/से) लिखने की आवश्यकता होती है, N जोड़ी की नहीं। +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 निष्पादक रणनीति पैटर्न +### 5.2 Executor Strategy Pattern -प्रत्येक प्रदाता के पास `BaseExecutor` से विरासत में मिला एक समर्पित निष्पादक वर्ग होता है। `executors/index.ts` में फ़ैक्टरी रनटाइम पर सही का चयन करती है। +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 स्व-पंजीकरण प्लगइन सिस्टम +### 5.3 Self-Registering Plugin System -अनुवादक मॉड्यूल `register()` के माध्यम से आयात पर स्वयं को पंजीकृत करते हैं। एक नया अनुवादक जोड़ने का अर्थ केवल एक फ़ाइल बनाना और उसे आयात करना है। +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 एक्सपोनेंशियल बैकऑफ़ के साथ खाता फ़ॉलबैक +### 5.4 Account Fallback with Exponential Backoff -जब कोई प्रदाता 429/401/500 लौटाता है, तो सिस्टम घातीय कूलडाउन (1s → 2s → 4s → अधिकतम 2 मिनट) लागू करते हुए, अगले खाते पर स्विच कर सकता है। +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 कॉम्बो मॉडल चेन +### 5.5 Combo Model Chains -एक "कॉम्बो" कई `provider/model` स्ट्रिंग्स को समूहित करता है। यदि पहला विफल हो जाता है, तो स्वचालित रूप से अगले पर फ़ॉलबैक हो जाता है। +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 स्टेटफुल स्ट्रीमिंग अनुवाद +### 5.6 Stateful Streaming Translation -प्रतिक्रिया अनुवाद `initState()` तंत्र के माध्यम से SSE खंडों (सोच ब्लॉक ट्रैकिंग, टूल कॉल संचय, सामग्री ब्लॉक अनुक्रमण) में स्थिति बनाए रखता है। +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 उपयोग सुरक्षा बफर +### 5.7 Usage Safety Buffer -सिस्टम संकेतों और प्रारूप अनुवाद से ओवरहेड के कारण ग्राहकों को संदर्भ विंडो सीमा तक पहुंचने से रोकने के लिए रिपोर्ट किए गए उपयोग में 2000-टोकन बफर जोड़ा गया है। +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. समर्थित प्रारूप +## 6. Supported Formats -| प्रारूप | दिशा | पहचानकर्ता | -| ---------------------- | -------------- | ------------------ | -| OpenAI चैट पूर्णताएँ | स्रोत + लक्ष्य | `openai` | -| ओपनएआई रिस्पॉन्स एपीआई | स्रोत + लक्ष्य | `openai-responses` | -| एंथ्रोपिक क्लाउड | स्रोत + लक्ष्य | `claude` | -| गूगल जेमिनी | स्रोत + लक्ष्य | `gemini` | -| गूगल जेमिनी सीएलआई | केवल लक्ष्य | `gemini-cli` | -| प्रतिगुरुत्वाकर्षण | स्रोत + लक्ष्य | `antigravity` | -| एडब्ल्यूएस किरो | केवल लक्ष्य | `kiro` | -| कर्सर | केवल लक्ष्य | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. समर्थित प्रदाता +## 7. Supported Providers -| प्रदाता | प्रामाणिक विधि | निष्पादक | मुख्य नोट्स | -| ------------------------ | -------------------------------- | ------------------ | ------------------------------------------------------ | -| एंथ्रोपिक क्लाउड | एपीआई कुंजी या OAuth | डिफ़ॉल्ट | `x-api-key` हेडर का उपयोग करता है | -| गूगल जेमिनी | एपीआई कुंजी या OAuth | डिफ़ॉल्ट | `x-goog-api-key` हेडर का उपयोग करता है | -| गूगल जेमिनी सीएलआई | OAuth | जेमिनीसीएलआई | `streamGenerateContent` समापन बिंदु का उपयोग करता है | -| प्रतिगुरुत्वाकर्षण | OAuth | प्रतिगुरुत्वाकर्षण | मल्टी-यूआरएल फ़ॉलबैक, कस्टम पुनः प्रयास पार्सिंग | -| ओपनएआई | एपीआई कुंजी | डिफ़ॉल्ट | मानक वाहक प्राधिकरण | -| कोडेक्स | OAuth | कोडेक्स | सिस्टम निर्देश इंजेक्ट करता है, सोच का प्रबंधन करता है | -| गिटहब कोपायलट | OAuth + सहपायलट टोकन | जीथूब | दोहरा टोकन, VSCode हेडर की नकल | -| किरो (एडब्ल्यूएस) | एडब्ल्यूएस एसएसओ ओआईडीसी या सोशल | किरो | बाइनरी इवेंटस्ट्रीम पार्सिंग | -| कर्सर आईडीई | चेकसम ऑथ | कर्सर | प्रोटोबफ़ एन्कोडिंग, SHA-256 चेकसम | -| क्वेन | OAuth | डिफ़ॉल्ट | मानक प्रमाणीकरण | -| आईफ्लो | OAuth (बेसिक + बियरर) | डिफ़ॉल्ट | डुअल ऑथ हेडर | -| ओपनराउटर | एपीआई कुंजी | डिफ़ॉल्ट | मानक वाहक प्राधिकरण | -| जीएलएम, किमी, मिनीमैक्स | एपीआई कुंजी | डिफ़ॉल्ट | क्लाउड-संगत, `x-api-key` का उपयोग करें | -| `openai-compatible-*` | एपीआई कुंजी | डिफ़ॉल्ट | गतिशील: कोई भी OpenAI-संगत समापन बिंदु | -| `anthropic-compatible-*` | एपीआई कुंजी | डिफ़ॉल्ट | गतिशील: कोई भी क्लाउड-संगत समापन बिंदु | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. डेटा प्रवाह सारांश +## 8. Data Flow Summary -### स्ट्रीमिंग अनुरोध +### Streaming Request -### गैर-स्ट्रीमिंग अनुरोध +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor\nbuildUrl + buildHeaders"] + D --> E["fetch(providerURL)"] + E --> F["createSSEStream()\nTRANSLATE mode"] + F --> G["parseSSELine()"] + G --> H["translateResponse()\ntarget → OpenAI → source"] + H --> I["extractUsage()\n+ addBuffer"] + I --> J["formatSSE()"] + J --> K["Client receives\ntranslated SSE"] + K --> L["logUsage()\nsaveRequestUsage()"] +``` -### बाईपास प्रवाह (क्लाउड सीएलआई) +### Non-Streaming Request + +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor.execute()"] + D --> E["translateResponse()\ntarget → OpenAI → source"] + E --> F["Return JSON\nresponse"] +``` + +### Bypass Flow (Claude CLI) + +```mermaid +flowchart LR + A["Claude CLI request"] --> B{"Match bypass\npattern?"} + B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"] + B -->|"No match"| D["Normal flow"] + C --> E["Translate to\nsource format"] + E --> F["Return without\ncalling provider"] +``` diff --git a/docs/i18n/in/FEATURES.md b/docs/i18n/in/FEATURES.md index bb70029782..82cc73b67b 100644 --- a/docs/i18n/in/FEATURES.md +++ b/docs/i18n/in/FEATURES.md @@ -1,69 +1,142 @@ -# ओमनीरूट - डैशबोर्ड फीचर गैलरी +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -ओमनीरूट डैशबोर्ड के प्रत्येक अनुभाग के लिए विज़ुअल गाइड। +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 प्रदाता +## 🔌 Providers -एआई प्रदाता कनेक्शन प्रबंधित करें: OAuth प्रदाता (क्लाउड कोड, कोडेक्स, जेमिनी सीएलआई), एपीआई कुंजी प्रदाता (ग्रोक, डीपसीक, ओपनराउटर), और मुफ्त प्रदाता (आईफ्लो, क्वेन, किरो)। +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨कॉम्बोज़ +## 🎨 Combos -6 रणनीतियों के साथ मॉडल रूटिंग कॉम्बो बनाएं: पहले भरें, राउंड-रॉबिन, दो-विकल्पों की शक्ति, यादृच्छिक, कम से कम उपयोग और लागत-अनुकूलित। प्रत्येक कॉम्बो स्वचालित फ़ॉलबैक के साथ कई मॉडलों को जोड़ता है। +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. + +![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 विश्लेषिकी +## 📊 Analytics -टोकन खपत, लागत अनुमान, गतिविधि हीटमैप, साप्ताहिक वितरण चार्ट और प्रति-प्रदाता विश्लेषण के साथ व्यापक उपयोग विश्लेषण। +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 सिस्टम हेल्थ +## 🏥 System Health -वास्तविक समय की निगरानी: अपटाइम, मेमोरी, संस्करण, विलंबता प्रतिशत (p50/p95/p99), कैश आँकड़े, और प्रदाता सर्किट ब्रेकर स्थिति। +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 अनुवादक खेल का मैदान +## 🔧 Translator Playground -एपीआई अनुवादों को डीबग करने के लिए चार मोड: **प्लेग्राउंड** (फॉर्मेट कनवर्टर), **चैट टेस्टर** (लाइव अनुरोध), **टेस्ट बेंच** (बैच टेस्ट), और **लाइव मॉनिटर** (रियल-टाइम स्ट्रीम)। +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ सेटिंग्स +## 🎮 Model Playground _(v2.0.9+)_ -सामान्य सेटिंग्स, सिस्टम स्टोरेज, बैकअप प्रबंधन (निर्यात/आयात डेटाबेस), उपस्थिति (डार्क/लाइट मोड), सुरक्षा (एपीआई एंडपॉइंट सुरक्षा और कस्टम प्रदाता ब्लॉकिंग शामिल है), रूटिंग, लचीलापन और उन्नत कॉन्फ़िगरेशन। +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. --- -## 🔧 सीएलआई उपकरण +## 🎨 Themes _(v2.0.5+)_ -एआई कोडिंग टूल के लिए एक-क्लिक कॉन्फ़िगरेशन: क्लाउड कोड, कोडेक्स सीएलआई, जेमिनी सीएलआई, ओपनक्लाव, किलो कोड और एंटीग्रेविटी। +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. --- -## 📝 अनुरोध लॉग +## ⚙️ Settings -प्रदाता, मॉडल, खाता और एपीआई कुंजी द्वारा फ़िल्टरिंग के साथ वास्तविक समय अनुरोध लॉगिंग। स्थिति कोड, टोकन उपयोग, विलंबता और प्रतिक्रिया विवरण दिखाता है। +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 CLI Tools + +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. + +![CLI Tools Dashboard](screenshots/07-cli-tools.png) + +--- + +## 🤖 CLI Agents _(v2.0.11+)_ + +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 एपीआई समापन बिंदु +## 🌐 API Endpoint -क्षमता विश्लेषण के साथ आपका एकीकृत एपीआई समापन बिंदु: चैट पूर्णताएं, एंबेडिंग, छवि निर्माण, पुनर्रैंकिंग, ऑडियो ट्रांसक्रिप्शन और पंजीकृत एपीआई कुंजी। +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. + +![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/in/TROUBLESHOOTING.md b/docs/i18n/in/TROUBLESHOOTING.md index 9b5bb6f400..120092d63c 100644 --- a/docs/i18n/in/TROUBLESHOOTING.md +++ b/docs/i18n/in/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +# Troubleshooting -#समस्या निवारण +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -ओम्निरूट के लिए सामान्य समस्याएं और समाधान। +Common problems and solutions for OmniRoute. --- -## त्वरित सुधार +## Quick Fixes -| समस्या | समाधान | -| -------------------------------------- | ------------------------------------------------------------------------------- | -| पहला लॉगिन काम नहीं कर रहा | `.env` में `INITIAL_PASSWORD` को जांचें (डिफ़ॉल्ट: `123456`) | -| गलत पोर्ट पर डैशबोर्ड खुलता है | `PORT=20128` और `NEXT_PUBLIC_BASE_URL=http://localhost:20128` सेट करें | -| `logs/` के अंतर्गत कोई अनुरोध लॉग नहीं | `ENABLE_REQUEST_LOGS=true` सेट करें | -| EACCES: अनुमति अस्वीकृत | `~/.omniroute` को ओवरराइड करने के लिए `DATA_DIR=/path/to/writable/dir` सेट करें | -| रूटिंग रणनीति सहेजी नहीं जा रही | v1.4.11+ पर अपडेट करें (सेटिंग्स दृढ़ता के लिए ज़ोड स्कीमा फिक्स) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## प्रदाता मुद्दे +## Provider Issues -### "भाषा मॉडल ने संदेश प्रदान नहीं किया" +### "Language model did not provide messages" -**कारण:** प्रदाता कोटा समाप्त हो गया। +**Cause:** Provider quota exhausted. -**ठीक करें:** +**Fix:** -1. डैशबोर्ड कोटा ट्रैकर की जाँच करें -2. फ़ॉलबैक टियर वाले कॉम्बो का उपयोग करें -3. सस्ते/मुफ़्त स्तर पर स्विच करें +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### दर सीमित करना +### Rate Limiting -**कारण:** सदस्यता कोटा समाप्त हो गया। +**Cause:** Subscription quota exhausted. -**ठीक करें:** +**Fix:** -- फ़ॉलबैक जोड़ें: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- सस्ते बैकअप के रूप में GLM/MiniMax का उपयोग करें +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth टोकन समाप्त हो गया +### OAuth Token Expired -ओम्निरूट स्वचालित रूप से टोकन ताज़ा करता है। यदि समस्याएँ बनी रहती हैं: +OmniRoute auto-refreshes tokens. If issues persist: -1. डैशबोर्ड → प्रदाता → पुनः कनेक्ट करें -2. प्रदाता कनेक्शन हटाएं और पुनः जोड़ें +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## बादल मुद्दे +## Cloud Issues -### क्लाउड सिंक त्रुटियाँ +### Cloud Sync Errors -1. अपने चल रहे उदाहरण के लिए `BASE_URL` अंक सत्यापित करें (उदाहरण के लिए, `http://localhost:20128`) -2. अपने क्लाउड एंडपॉइंट पर `CLOUD_URL` पॉइंट सत्यापित करें (जैसे, `https://omniroute.dev`) -3. `NEXT_PUBLIC_*` मानों को सर्वर-साइड मानों के साथ संरेखित रखें +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### क्लाउड `stream=false` 500 लौटाता है +### Cloud `stream=false` Returns 500 -**लक्षण:** गैर-स्ट्रीमिंग कॉल के लिए क्लाउड एंडपॉइंट पर `Unexpected token 'd'...`। +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**कारण:** अपस्ट्रीम एसएसई पेलोड लौटाता है जबकि ग्राहक JSON की अपेक्षा करता है। +**Cause:** Upstream returns SSE payload while client expects JSON. -**समाधान:** क्लाउड डायरेक्ट कॉल के लिए `stream=true` का उपयोग करें। स्थानीय रनटाइम में SSE→JSON फ़ॉलबैक शामिल है। +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### क्लाउड कहता है कनेक्टेड लेकिन "अमान्य एपीआई कुंजी" +### Cloud Says Connected but "Invalid API key" -1. स्थानीय डैशबोर्ड से एक नई कुंजी बनाएं (`/api/keys`) -2. क्लाउड सिंक चलाएँ: क्लाउड सक्षम करें → अभी सिंक करें -3. पुरानी/गैर-सिंक की गई कुंजियाँ अभी भी क्लाउड पर `401` लौटा सकती हैं +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## डॉकर मुद्दे +## Docker Issues -### सीएलआई टूल शो स्थापित नहीं है +### CLI Tool Shows Not Installed -1. रनटाइम फ़ील्ड जांचें: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. पोर्टेबल मोड के लिए: छवि लक्ष्य `runner-cli` (बंडल सीएलआई) का उपयोग करें -3. होस्ट माउंट मोड के लिए: `CLI_EXTRA_PATHS` सेट करें और होस्ट बिन निर्देशिका को केवल पढ़ने के लिए माउंट करें -4. यदि `installed=true` और `runnable=false`: बाइनरी पाई गई लेकिन स्वास्थ्य जांच विफल रही +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### त्वरित रनटाइम सत्यापन +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,121 +91,164 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## लागत संबंधी मुद्दे +## Cost Issues -### उच्च लागत +### High Costs -1. डैशबोर्ड → उपयोग में उपयोग के आँकड़े जाँचें -2. प्राथमिक मॉडल को जीएलएम/मिनीमैक्स पर स्विच करें -3. गैर-महत्वपूर्ण कार्यों के लिए फ्री टियर (मिथुन सीएलआई, आईफ्लो) का उपयोग करें -4. प्रति एपीआई कुंजी लागत बजट निर्धारित करें: डैशबोर्ड → एपीआई कुंजी → बजट +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## डिबगिंग +## Debugging -### अनुरोध लॉग सक्षम करें +### Enable Request Logs -अपनी `.env` फ़ाइल में `ENABLE_REQUEST_LOGS=true` सेट करें। लॉग `logs/` निर्देशिका के अंतर्गत दिखाई देते हैं। +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### प्रदाता के स्वास्थ्य की जाँच करें +### Check Provider Health -### रनटाइम स्टोरेज +```bash +# Health dashboard +http://localhost:20128/dashboard/health -- मुख्य स्थिति: `${DATA_DIR}/db.json` (प्रदाता, कॉम्बो, उपनाम, कुंजियाँ, सेटिंग्स) -- उपयोग: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- अनुरोध लॉग: `/logs/...` (जब `ENABLE_REQUEST_LOGS=true`) +# API health check +curl http://localhost:20128/api/monitoring/health +``` + +### Runtime Storage + +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## सर्किट ब्रेकर मुद्दे +## Circuit Breaker Issues -### प्रदाता खुली स्थिति में फंसा हुआ है +### Provider stuck in OPEN state -जब किसी प्रदाता का सर्किट ब्रेकर खुला होता है, तो कूलडाउन समाप्त होने तक अनुरोध अवरुद्ध हो जाते हैं। +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**ठीक करें:** +**Fix:** -1. **डैशबोर्ड → सेटिंग्स → लचीलापन** पर जाएं -2. प्रभावित प्रदाता के लिए सर्किट ब्रेकर कार्ड की जाँच करें -3. सभी ब्रेकर साफ़ करने के लिए **रीसेट ऑल** पर क्लिक करें, या कूलडाउन समाप्त होने तक प्रतीक्षा करें -4. रीसेट करने से पहले सत्यापित करें कि प्रदाता वास्तव में उपलब्ध है +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### प्रदाता सर्किट ब्रेकर को ट्रिप करता रहता है +### Provider keeps tripping the circuit breaker -यदि कोई प्रदाता बार-बार खुली स्थिति में प्रवेश करता है: +If a provider repeatedly enters OPEN state: -1. विफलता पैटर्न के लिए **डैशबोर्ड → स्वास्थ्य → प्रदाता स्वास्थ्य** की जाँच करें -2. **सेटिंग्स → लचीलापन → प्रदाता प्रोफाइल** पर जाएं और विफलता सीमा बढ़ाएं -3. जांचें कि क्या प्रदाता ने एपीआई सीमाएं बदल दी हैं या पुनः प्रमाणीकरण की आवश्यकता है -4. विलंबता टेलीमेट्री की समीक्षा करें - उच्च विलंबता टाइमआउट-आधारित विफलताओं का कारण बन सकती है +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## ऑडियो ट्रांस्क्रिप्शन मुद्दे +## Audio Transcription Issues -### "असमर्थित मॉडल" त्रुटि +### "Unsupported model" error -- सुनिश्चित करें कि आप सही उपसर्ग का उपयोग कर रहे हैं: `deepgram/nova-3` या `assemblyai/best` -- सत्यापित करें कि प्रदाता **डैशबोर्ड → प्रदाता** में जुड़ा हुआ है +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### प्रतिलेखन खाली या विफल रहता है +### Transcription returns empty or fails -- समर्थित ऑडियो प्रारूप जांचें: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- सत्यापित करें कि फ़ाइल का आकार प्रदाता सीमा के भीतर है (आमतौर पर <25MB) -- प्रदाता कार्ड में प्रदाता एपीआई कुंजी वैधता की जांच करें +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## अनुवादक डिबगिंग +## Translator Debugging -प्रारूप अनुवाद समस्याओं को डीबग करने के लिए **डैशबोर्ड → अनुवादक** का उपयोग करें: +Use **Dashboard → Translator** to debug format translation issues: -| मोड | कब उपयोग करें | -| ---------------- | ------------------------------------------------------------------------------------------------------------- | -| **खेल का मैदान** | इनपुट/आउटपुट स्वरूपों की साथ-साथ तुलना करें - यह कैसे अनुवादित होता है यह देखने के लिए एक असफल अनुरोध चिपकाएँ | -| **चैट परीक्षक** | लाइव संदेश भेजें और हेडर सहित पूर्ण अनुरोध/प्रतिक्रिया पेलोड का निरीक्षण करें | -| **टेस्ट बेंच** | यह पता लगाने के लिए कि कौन से अनुवाद टूटे हुए हैं, सभी प्रारूप संयोजनों में बैच परीक्षण चलाएँ | -| **लाइव मॉनिटर** | रुक-रुक कर होने वाली अनुवाद समस्याओं को पकड़ने के लिए वास्तविक समय अनुरोध प्रवाह देखें | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### सामान्य प्रारूप मुद्दे +### Common format issues -- **सोच टैग दिखाई नहीं दे रहे हैं** - जांचें कि क्या लक्ष्य प्रदाता सोच और सोच बजट सेटिंग का समर्थन करता है -- **टूल कॉल ड्रॉपिंग** — कुछ प्रारूप अनुवाद असमर्थित फ़ील्ड को हटा सकते हैं; खेल का मैदान मोड में सत्यापित करें -- **सिस्टम प्रॉम्प्ट गायब** — क्लाउड और जेमिनी हैंडल सिस्टम प्रॉम्प्ट अलग-अलग होते हैं; अनुवाद आउटपुट की जाँच करें -- **एसडीके ऑब्जेक्ट के बजाय कच्ची स्ट्रिंग लौटाता है** - v1.1.0 में फिक्स्ड: रिस्पॉन्स सैनिटाइज़र अब गैर-मानक फ़ील्ड्स (`x_groq`, `usage_breakdown`, आदि) को हटा देता है जो OpenAI SDK पायडेंटिक सत्यापन विफलताओं का कारण बनता है -- **GLM/ERNIE `system` भूमिका को अस्वीकार करता है** - v1.1.0 में फिक्स्ड: रोल नॉर्मलाइज़र स्वचालित रूप से असंगत मॉडल के लिए सिस्टम संदेशों को उपयोगकर्ता संदेशों में मर्ज कर देता है -- **`developer` भूमिका पहचानी नहीं गई** - v1.1.0 में ठीक किया गया: गैर-ओपनएआई प्रदाताओं के लिए स्वचालित रूप से `system` में परिवर्तित हो गया -- **`json_schema` मिथुन राशि के साथ काम नहीं कर रहा** - v1.1.0 में ठीक किया गया: `response_format` अब मिथुन राशि के `responseMimeType` + `responseSchema` में परिवर्तित हो गया है +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## लचीलापन सेटिंग्स +## Resilience Settings -### स्वचालित दर-सीमा ट्रिगर नहीं हो रही है +### Auto rate-limit not triggering -- ऑटो दर-सीमा केवल एपीआई कुंजी प्रदाताओं पर लागू होती है (OAuth/सदस्यता पर नहीं) -- सत्यापित करें **सेटिंग्स → लचीलापन → प्रदाता प्रोफाइल** में ऑटो-दर-सीमा सक्षम है -- जांचें कि क्या प्रदाता `429` स्टेटस कोड या `Retry-After` हेडर लौटाता है +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### ट्यूनिंग घातीय बैकऑफ़ +### Tuning exponential backoff -प्रदाता प्रोफ़ाइल इन सेटिंग्स का समर्थन करती हैं: +Provider profiles support these settings: -- **आधार विलंब** — पहली विफलता के बाद प्रारंभिक प्रतीक्षा समय (डिफ़ॉल्ट: 1 सेकंड) -- **अधिकतम विलंब** — अधिकतम प्रतीक्षा समय सीमा (डिफ़ॉल्ट: 30s) -- **गुणक** - लगातार विफलता के बाद विलंब को कितना बढ़ाया जाए (डिफ़ॉल्ट: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### वज्र-विरोधी झुंड +### Anti-thundering herd -जब कई समवर्ती अनुरोध एक दर-सीमित प्रदाता से टकराते हैं, तो ओमनीरूट अनुरोधों को क्रमबद्ध करने और कैस्केडिंग विफलताओं को रोकने के लिए म्यूटेक्स + ऑटो रेट-लिमिटिंग का उपयोग करता है। यह एपीआई कुंजी प्रदाताओं के लिए स्वचालित है। +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## अभी भी अटका हुआ है? +## Optional RAG / LLM failure taxonomy (16 problems) -- **गिटहब मुद्दे**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **आर्किटेक्चर**: आंतरिक विवरण के लिए [link](ARCHITECTURE.md) देखें -- **एपीआई संदर्भ**: सभी समापन बिंदुओं के लिए [link](API_REFERENCE.md) देखें -- **स्वास्थ्य डैशबोर्ड**: वास्तविक समय प्रणाली की स्थिति के लिए **डैशबोर्ड → स्वास्थ्य** जांचें -- **अनुवादक**: प्रारूप संबंधी समस्याओं को डीबग करने के लिए **डैशबोर्ड → अनुवादक** का उपयोग करें +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/in/USER_GUIDE.md b/docs/i18n/in/USER_GUIDE.md index 9be90fd046..5a043224df 100644 --- a/docs/i18n/in/USER_GUIDE.md +++ b/docs/i18n/in/USER_GUIDE.md @@ -1,12 +1,12 @@ -# उपयोगकर्ता गाइड +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -प्रदाताओं को कॉन्फ़िगर करने, कॉम्बो बनाने, सीएलआई टूल को एकीकृत करने और ओमनीरूट को तैनात करने के लिए संपूर्ण मार्गदर्शिका। +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## सामग्री तालिका +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 मूल्य निर्धारण एक नज़र में +## 💰 Pricing at a Glance -| टियर | प्रदाता | लागत | कोटा रीसेट | के लिए सर्वश्रेष्ठ | -| ----------------- | ------------------- | ----------------------- | -------------------- | ---------------------------- | -| **💳 सदस्यता** | क्लाउड कोड (प्रो) | $20/माह | 5 घंटे + साप्ताहिक | पहले ही सदस्यता ले ली है | -| | कोडेक्स (प्लस/प्रो) | $20-200/महीना | 5 घंटे + साप्ताहिक | OpenAI उपयोगकर्ता | -| | जेमिनी सीएलआई | **मुफ़्त** | 180K/माह + 1K/दिन | सब लोग! | -| | गिटहब कोपायलट | $10-19/माह | मासिक | GitHub उपयोगकर्ता | -| **🔑एपीआई कुंजी** | डीपसीक | प्रति उपयोग भुगतान करें | कोई नहीं | सस्ता तर्क | -| | ग्रोक | प्रति उपयोग भुगतान करें | कोई नहीं | अल्ट्रा-फास्ट अनुमान | -| | एक्सएआई (ग्रोक) | प्रति उपयोग भुगतान करें | कोई नहीं | ग्रोक 4 तर्क | -| | मिस्ट्रल | प्रति उपयोग भुगतान करें | कोई नहीं | ईयू द्वारा होस्ट किए गए मॉडल | -| | उलझन | प्रति उपयोग भुगतान करें | कोई नहीं | खोज-संवर्धित | -| | एक साथ एआई | प्रति उपयोग भुगतान करें | कोई नहीं | ओपन-सोर्स मॉडल | -| | आतिशबाजी एआई | प्रति उपयोग भुगतान करें | कोई नहीं | फास्ट फ्लक्स छवियां | -| | सेरेब्रस | प्रति उपयोग भुगतान करें | कोई नहीं | वेफर-स्केल गति | -| | सहभागी | प्रति उपयोग भुगतान करें | कोई नहीं | कमांड आर+आरएजी | -| | एनवीडिया एनआईएम | प्रति उपयोग भुगतान करें | कोई नहीं | एंटरप्राइज़ मॉडल | -| **💰सस्ता** | जीएलएम-4.7 | $0.6/1 मिलियन | प्रतिदिन सुबह 10 बजे | बजट बैकअप | -| | मिनीमैक्स एम2.1 | $0.2/1 मिलियन | 5 घंटे की रोलिंग | सबसे सस्ता विकल्प | -| | किमी K2 | $9/महीना फ्लैट | 10एम टोकन/माह | अनुमानित लागत | -| **🆓 मुफ़्त** | आईफ्लो | $0 | असीमित | 8 मॉडल निःशुल्क | -| | क्वेन | $0 | असीमित | 3 मॉडल मुफ़्त | -| | किरो | $0 | असीमित | क्लाउड मुक्त | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 प्रो टिप:** जेमिनी सीएलआई (180 हजार निःशुल्क/माह) + आईफ्लो (असीमित निःशुल्क) कॉम्बो = $0 लागत से शुरू करें! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 उपयोग के मामले +## 🎯 Use Cases -### केस 1: "मेरे पास क्लाउड प्रो सदस्यता है" +### Case 1: "I have Claude Pro subscription" -**समस्या:** भारी कोडिंग के दौरान कोटा अप्रयुक्त, दर सीमा समाप्त हो जाता है +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,13 +63,23 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### केस 2: "मुझे शून्य लागत चाहिए" +### Case 2: "I want zero cost" -**समस्या:** सदस्यताएं वहन नहीं कर सकते, विश्वसनीय एआई कोडिंग की आवश्यकता है +**Problem:** Can't afford subscriptions, need reliable AI coding -### केस 3: "मुझे 24/7 कोडिंग चाहिए, कोई रुकावट नहीं" +``` +Combo: "free-forever" + 1. gc/gemini-3-flash (180K free/month) + 2. if/kimi-k2-thinking (unlimited free) + 3. qw/qwen3-coder-plus (unlimited free) -**समस्या:** समय सीमा, डाउनटाइम बर्दाश्त नहीं कर सकते +Monthly cost: $0 +Quality: Production-ready models +``` + +### Case 3: "I need 24/7 coding, no interruptions" + +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -83,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### केस 4: "मुझे ओपनक्लॉ में मुफ़्त एआई चाहिए" +### Case 4: "I want FREE AI in OpenClaw" -**समस्या:** मैसेजिंग ऐप्स में AI सहायक की आवश्यकता है, पूरी तरह से निःशुल्क +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -99,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 प्रदाता सेटअप +## 📖 Provider Setup -### 🔐 सदस्यता प्रदाता +### 🔐 Subscription Providers -#### क्लाउड कोड (प्रो/मैक्स) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -116,15 +126,35 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**प्रो टिप:** जटिल कार्यों के लिए ओपस और गति के लिए सॉनेट का उपयोग करें। ओमनीरूट प्रति मॉडल कोटा ट्रैक करता है! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### ओपनएआई कोडेक्स (प्लस/प्रो) +#### OpenAI Codex (Plus/Pro) -#### जेमिनी सीएलआई (मुफ़्त 180K/माह!) +```bash +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset -**सर्वोत्तम मूल्य:** विशाल निःशुल्क स्तर! सशुल्क स्तरों से पहले इसका उपयोग करें। +Models: + cx/gpt-5.2-codex + cx/gpt-5.1-codex-max +``` -#### गिटहब कोपायलट +#### Gemini CLI (FREE 180K/month!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**Best Value:** Huge free tier! Use this before paid tiers. + +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -137,35 +167,41 @@ Models: gh/gemini-3-pro ``` -### 💰 सस्ते प्रदाता +### 💰 Cheap Providers -#### GLM-4.7 (दैनिक रीसेट, $0.6/1 मिलियन) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. साइन अप करें: [Zhipu AI](https://open.bigmodel.cn/) -2. कोडिंग योजना से एपीआई कुंजी प्राप्त करें -3. डैशबोर्ड → एपीआई कुंजी जोड़ें: प्रदाता: `glm`, एपीआई कुंजी: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**उपयोग करें:** `glm/glm-4.7` - **प्रो टिप:** कोडिंग प्लान 1/7 लागत पर 3× कोटा प्रदान करता है! प्रतिदिन सुबह 10:00 बजे रीसेट करें। +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### मिनीमैक्स एम2.1 (5 घंटे रीसेट, $0.20/1 मिलियन) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. साइन अप करें: [MiniMax](https://www.minimax.io/) -2. एपीआई कुंजी प्राप्त करें → डैशबोर्ड → एपीआई कुंजी जोड़ें +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**उपयोग करें:** `minimax/MiniMax-M2.1` - **प्रो टिप:** लंबे संदर्भ के लिए सबसे सस्ता विकल्प (1M टोकन)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### किमी K2 ($9/माह फ्लैट) +#### Kimi K2 ($9/month flat) -1. सदस्यता लें: [Moonshot AI](https://platform.moonshot.ai/) -2. एपीआई कुंजी प्राप्त करें → डैशबोर्ड → एपीआई कुंजी जोड़ें +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**उपयोग करें:** `kimi/kimi-latest` - **प्रो टिप:** 10M टोकन के लिए निश्चित $9/माह = $0.90/1M प्रभावी लागत! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 निःशुल्क प्रदाता +### 🆓 FREE Providers -#### आईफ्लो (8 मुफ़्त मॉडल) +#### iFlow (8 FREE models) -#### क्वेन (3 मुफ़्त मॉडल) +```bash +Dashboard → Connect iFlow → OAuth login → Unlimited usage + +Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 +``` + +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -173,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### किरो (क्लाउड फ्री) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -183,112 +219,268 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨कॉम्बोज़ +## 🎨 Combos -### उदाहरण 1: सदस्यता अधिकतम करें → सस्ता बैकअप +### Example 1: Maximize Subscription → Cheap Backup -### उदाहरण 2: केवल निःशुल्क (शून्य लागत) +``` +Dashboard → Combos → Create New + +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) + +Use in CLI: premium-coding +``` + +### Example 2: Free-Only (Zero Cost) + +``` +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) + +Cost: $0 forever! +``` --- -## 🔧 सीएलआई एकीकरण +## 🔧 CLI Integration -### कर्सर आईडीई +### Cursor IDE -### क्लाउड कोड +``` +Settings → Models → Advanced: + OpenAI API Base URL: http://localhost:20128/v1 + OpenAI API Key: [from omniroute dashboard] + Model: cc/claude-opus-4-6 +``` -संपादित करें `~/.claude/config.json`: +### Claude Code -### कोडेक्स सीएलआई +Edit `~/.claude/config.json`: -### ओपनक्लॉ +```json +{ + "anthropic_api_base": "http://localhost:20128/v1", + "anthropic_api_key": "your-omniroute-api-key" +} +``` -संपादित करें `~/.openclaw/openclaw.json`: +### Codex CLI -**या डैशबोर्ड का उपयोग करें:** सीएलआई टूल्स → ओपनक्लॉ → ऑटो-कॉन्फ़िगरेशन +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" +codex "your prompt" +``` -### क्लाइन / जारी रखें / रूकोड +### OpenClaw + +Edit `~/.openclaw/openclaw.json`: + +```json +{ + "agents": { + "defaults": { + "model": { "primary": "omniroute/if/glm-4.7" } + } + }, + "models": { + "providers": { + "omniroute": { + "baseUrl": "http://localhost:20128/v1", + "apiKey": "your-omniroute-api-key", + "api": "openai-completions", + "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }] + } + } + } +} +``` + +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config + +### Cline / Continue / RooCode + +``` +Provider: OpenAI Compatible +Base URL: http://localhost:20128/v1 +API Key: [from dashboard] +Model: cc/claude-opus-4-6 +``` --- -## 🚀 परिनियोजन +## 🚀 Deployment -### वीपीएस परिनियोजन +### Global npm install (Recommended) -### डॉकर +```bash +npm install -g omniroute -सीएलआई बायनेरिज़ के साथ होस्ट-एकीकृत मोड के लिए, मुख्य दस्तावेज़ में डॉकर अनुभाग देखें। +# Create config directory +mkdir -p ~/.omniroute -### पर्यावरण चर +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env -| परिवर्तनीय | डिफ़ॉल्ट | विवरण | -| --------------------- | ------------------------------------ | ------------------------------------------------------ | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT हस्ताक्षर रहस्य (**उत्पादन में परिवर्तन**) | -| `INITIAL_PASSWORD` | `123456` | पहला लॉगिन पासवर्ड | -| `DATA_DIR` | `~/.omniroute` | डेटा निर्देशिका (डीबी, उपयोग, लॉग) | -| `PORT` | फ्रेमवर्क डिफ़ॉल्ट | सर्विस पोर्ट (उदाहरणों में `20128`) | -| `HOSTNAME` | फ्रेमवर्क डिफ़ॉल्ट | बाइंड होस्ट (डॉकर डिफ़ॉल्ट रूप से `0.0.0.0`) | -| `NODE_ENV` | रनटाइम डिफ़ॉल्ट | तैनाती के लिए `production` सेट करें | -| `BASE_URL` | `http://localhost:20128` | सर्वर-साइड आंतरिक आधार URL | -| `CLOUD_URL` | `https://omniroute.dev` | क्लाउड सिंक एंडपॉइंट बेस यूआरएल | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | जेनरेट की गई एपीआई कुंजियों के लिए एचएमएसी रहस्य | -| `REQUIRE_API_KEY` | `false` | `/v1/*` पर बियरर एपीआई कुंजी लागू करें | -| `ENABLE_REQUEST_LOGS` | `false` | अनुरोध/प्रतिक्रिया लॉग सक्षम करता है | -| `AUTH_COOKIE_SECURE` | `false` | फोर्स `Secure` ऑथ कुकी (HTTPS रिवर्स प्रॉक्सी के पीछे) | +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` -संपूर्ण पर्यावरण चर संदर्भ के लिए, [README](../README.md) देखें। +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment + +```bash +git clone https://github.com/diegosouzapw/OmniRoute.git +cd OmniRoute && npm install && npm run build + +export JWT_SECRET="your-secure-secret-change-this" +export INITIAL_PASSWORD="your-password" +export DATA_DIR="/var/lib/omniroute" +export PORT="20128" +export HOSTNAME="0.0.0.0" +export NODE_ENV="production" +export NEXT_PUBLIC_BASE_URL="http://localhost:20128" +export API_KEY_SECRET="endpoint-proxy-api-key-secret" + +npm run start +# Or: pm2 start npm --name omniroute -- start +``` + +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker + +```bash +# Build image (default = runner-cli with codex/claude/droid preinstalled) +docker build -t omniroute:cli . + +# Portable mode (recommended) +docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli +``` + +For host-integrated mode with CLI binaries, see the Docker section in the main docs. + +### Environment Variables + +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | + +For the full environment variable reference, see the [README](../README.md). --- -## 📊 उपलब्ध मॉडल +## 📊 Available Models -सभी उपलब्ध मॉडल देखें +
+View all available models -**क्लाउड कोड (`cc/`)** — प्रो/मैक्स: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**कोडेक्स (`cx/`)** — प्लस/प्रो: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**मिथुन सीएलआई (`gc/`)** — मुफ़्त: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**गिटहब कोपायलट (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**जीएलएम (`glm/`)** — $0.6/1M: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**मिनीमैक्स (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — मुफ़्त: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**क्वेन (`qw/`)** — मुफ़्त: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**किरो (`kr/`)** — मुफ़्त: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` -**डीपसीक (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` -**ग्रोक (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` **xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**मिस्ट्रल (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**व्याकुलता (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**एक साथ AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**आतिशबाजी एआई (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**सेरेब्रस (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**यहां (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` -**एनवीडिया एनआईएम (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
--- -## 🧩 उन्नत सुविधाएँ +## 🧩 Advanced Features -### कस्टम मॉडल +### Custom Models -ऐप अपडेट की प्रतीक्षा किए बिना किसी भी प्रदाता से कोई भी मॉडल आईडी जोड़ें: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -300,153 +492,201 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -या डैशबोर्ड का उपयोग करें: **प्रदाता → [प्रदाता] → कस्टम मॉडल**। +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### समर्पित प्रदाता मार्ग +### Dedicated Provider Routes -मॉडल सत्यापन के साथ सीधे एक विशिष्ट प्रदाता को रूट अनुरोध: +Route requests directly to a specific provider with model validation: -गायब होने पर प्रदाता उपसर्ग स्वतः जुड़ जाता है। बेमेल मॉडल `400` लौटाते हैं। +```bash +POST http://localhost:20128/v1/providers/openai/chat/completions +POST http://localhost:20128/v1/providers/openai/embeddings +POST http://localhost:20128/v1/providers/fireworks/images/generations +``` -### नेटवर्क प्रॉक्सी कॉन्फ़िगरेशन +The provider prefix is auto-added if missing. Mismatched models return `400`. -**प्राथमिकता:** कुंजी-विशिष्ट → कॉम्बो-विशिष्ट → प्रदाता-विशिष्ट → वैश्विक → पर्यावरण। +### Network Proxy Configuration -### मॉडल कैटलॉग एपीआई +```bash +# Set global proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}' -प्रदाता द्वारा प्रकारों (`chat`, `embedding`, `image`) के साथ समूहीकृत मॉडल लौटाता है। +# Per-provider proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}' -### क्लाउड सिंक +# Test proxy +curl -X POST http://localhost:20128/api/settings/proxy/test \ + -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' +``` -- सभी डिवाइसों में सिंक प्रदाता, कॉम्बो और सेटिंग्स -- टाइमआउट + फेल-फास्ट के साथ स्वचालित पृष्ठभूमि सिंक -- उत्पादन में सर्वर-साइड `BASE_URL`/`CLOUD_URL` को प्राथमिकता दें +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### एलएलएम गेटवे इंटेलिजेंस (चरण 9) +### Model Catalog API -- **सिमेंटिक कैश** - ऑटो-कैश नॉन-स्ट्रीमिंग, तापमान = 0 प्रतिक्रियाएँ (`X-OmniRoute-No-Cache: true` के साथ बायपास) -- **इडेम्पोटेंसी का अनुरोध करें** - `Idempotency-Key` या `X-Request-Id` हेडर के माध्यम से 5s के भीतर अनुरोधों को डीडुप्लिकेट करता है -- **प्रगति ट्रैकिंग** - `X-OmniRoute-Progress: true` हेडर के माध्यम से SSE `event: progress` इवेंट में ऑप्ट-इन करें +```bash +curl http://localhost:20128/api/models/catalog +``` + +Returns models grouped by provider with types (`chat`, `embedding`, `image`). + +### Cloud Sync + +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production + +### LLM Gateway Intelligence (Phase 9) + +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### अनुवादक खेल का मैदान +### Translator Playground -**डैशबोर्ड → अनुवादक** के माध्यम से पहुंच। डीबग करें और कल्पना करें कि कैसे ओमनीरूट प्रदाताओं के बीच एपीआई अनुरोधों का अनुवाद करता है। +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| मोड | उद्देश्य | -| ---------------- | -------------------------------------------------------------------------------------------- | -| **खेल का मैदान** | स्रोत/लक्ष्य प्रारूप चुनें, एक अनुरोध चिपकाएँ, और अनुवादित आउटपुट तुरंत देखें | -| **चैट परीक्षक** | प्रॉक्सी के माध्यम से लाइव चैट संदेश भेजें और पूर्ण अनुरोध/प्रतिक्रिया चक्र का निरीक्षण करें | -| **टेस्ट बेंच** | अनुवाद की शुद्धता को सत्यापित करने के लिए कई प्रारूप संयोजनों में बैच परीक्षण चलाएँ | -| **लाइव मॉनिटर** | प्रॉक्सी के माध्यम से अनुरोध प्रवाहित होने पर वास्तविक समय में अनुवाद देखें | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**उपयोग के मामले:** +**Use cases:** -- डीबग करें कि कोई विशिष्ट ग्राहक/प्रदाता संयोजन विफल क्यों होता है -- सत्यापित करें कि थिंकिंग टैग, टूल कॉल और सिस्टम प्रॉम्प्ट सही ढंग से अनुवाद करते हैं -- ओपनएआई, क्लाउड, जेमिनी और रिस्पॉन्स एपीआई प्रारूपों के बीच प्रारूप अंतर की तुलना करें +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### रूटिंग रणनीतियाँ +### Routing Strategies -**डैशबोर्ड → सेटिंग्स → रूटिंग** के माध्यम से कॉन्फ़िगर करें। +Configure via **Dashboard → Settings → Routing**. -| रणनीति | विवरण | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | -| **पहले भरें** | प्राथमिकता क्रम में खातों का उपयोग करता है - प्राथमिक खाता अनुपलब्ध होने तक सभी अनुरोधों को संभालता है | -| **राउंड रॉबिन** | एक विन्यास योग्य चिपचिपा सीमा के साथ सभी खातों के माध्यम से चक्र (डिफ़ॉल्ट: प्रति खाता 3 कॉल) | -| **पी2सी (दो विकल्पों की शक्ति)** | 2 यादृच्छिक खाते चुनता है और स्वस्थ खाते की ओर ले जाता है - स्वास्थ्य के प्रति जागरूकता के साथ भार संतुलित करता है | -| **यादृच्छिक** | फिशर-येट्स शफल | का उपयोग करके प्रत्येक अनुरोध के लिए यादृच्छिक रूप से एक खाता चुनता है | -| **कम से कम इस्तेमाल** | सबसे पुराने `lastUsedAt` टाइमस्टैम्प के साथ खाते तक रूट, ट्रैफ़िक को समान रूप से वितरित करना | -| **लागत अनुकूलित** | सबसे कम लागत वाले प्रदाताओं के लिए अनुकूलन, सबसे कम प्राथमिकता मूल्य वाले खाते तक रूट | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### वाइल्डकार्ड मॉडल उपनाम +#### Wildcard Model Aliases -मॉडल नामों को रीमैप करने के लिए वाइल्डकार्ड पैटर्न बनाएं: +Create wildcard patterns to remap model names: -वाइल्डकार्ड `*` (कोई भी वर्ण) और `?` (एकल वर्ण) का समर्थन करते हैं। +``` +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 +Pattern: gpt-* → Target: gh/gpt-5.1-codex +``` -#### फ़ॉलबैक चेन +Wildcards support `*` (any characters) and `?` (single character). -वैश्विक फ़ॉलबैक श्रृंखलाओं को परिभाषित करें जो सभी अनुरोधों पर लागू होती हैं: +#### Fallback Chains + +Define global fallback chains that apply across all requests: + +``` +Chain: production-fallback + 1. cc/claude-opus-4-6 + 2. gh/gpt-5.1-codex + 3. glm/glm-4.7 +``` --- -### लचीलापन और सर्किट ब्रेकर +### Resilience & Circuit Breakers -**डैशबोर्ड → सेटिंग्स → लचीलापन** के माध्यम से कॉन्फ़िगर करें। +Configure via **Dashboard → Settings → Resilience**. -ओमनीरूट चार घटकों के साथ प्रदाता-स्तरीय लचीलापन लागू करता है: +OmniRoute implements provider-level resilience with four components: -1. **प्रदाता प्रोफाइल** - प्रति-प्रदाता कॉन्फ़िगरेशन: - - विफलता सीमा (उद्घाटन से पहले कितनी विफलताएं) - - कूलडाउन अवधि - - दर सीमा का पता लगाने की संवेदनशीलता - - घातीय बैकऑफ़ पैरामीटर +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **संपादन योग्य दर सीमाएँ** — डैशबोर्ड में कॉन्फ़िगर करने योग्य सिस्टम-स्तरीय डिफ़ॉल्ट: - - **प्रति मिनट अनुरोध (आरपीएम)** - प्रति खाता प्रति मिनट अधिकतम अनुरोध - - **अनुरोधों के बीच न्यूनतम समय** - अनुरोधों के बीच मिलीसेकंड में न्यूनतम अंतर - - **अधिकतम समवर्ती अनुरोध** — प्रति खाता अधिकतम एक साथ अनुरोध - - संशोधित करने के लिए **संपादित करें** पर क्लिक करें, फिर **सहेजें** या **रद्द करें** पर क्लिक करें। मान लचीलापन एपीआई के माध्यम से बने रहते हैं। +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **सर्किट ब्रेकर** - प्रति प्रदाता विफलताओं को ट्रैक करता है और सीमा तक पहुंचने पर स्वचालित रूप से सर्किट खोलता है: - - **बंद** (स्वस्थ) - अनुरोध सामान्य रूप से प्रवाहित होते हैं - - **खुला** - बार-बार विफलताओं के बाद प्रदाता अस्थायी रूप से अवरुद्ध हो जाता है - - **आधा_खुला** — परीक्षण किया जा रहा है कि प्रदाता ठीक हो गया है या नहीं +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **नीतियाँ और लॉक किए गए पहचानकर्ता** - बल-अनलॉक क्षमता के साथ सर्किट ब्रेकर की स्थिति और लॉक किए गए पहचानकर्ताओं को दिखाता है। +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **दर सीमा ऑटो-डिटेक्शन** - प्रदाता दर सीमा से बचने के लिए `429` और `Retry-After` हेडर मॉनिटर करता है। +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**प्रो टिप:** जब कोई प्रदाता आउटेज से उबरता है तो सभी सर्किट ब्रेकर और कूलडाउन को साफ़ करने के लिए **रीसेट ऑल** बटन का उपयोग करें। +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### डेटाबेस निर्यात/आयात +### Database Export / Import -**डैशबोर्ड → सेटिंग्स → सिस्टम और स्टोरेज** में डेटाबेस बैकअप प्रबंधित करें। +Manage database backups in **Dashboard → Settings → System & Storage**. -| कार्रवाई | विवरण | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| **डेटाबेस निर्यात करें** | वर्तमान SQLite डेटाबेस को `.sqlite` फ़ाइल के रूप में डाउनलोड करता है | -| **सभी निर्यात करें (.tar.gz)** | एक पूर्ण बैकअप संग्रह डाउनलोड करता है जिसमें शामिल हैं: डेटाबेस, सेटिंग्स, कॉम्बो, प्रदाता कनेक्शन (कोई क्रेडेंशियल नहीं), एपीआई कुंजी मेटाडेटा | -| **डेटाबेस आयात करें** | वर्तमान डेटाबेस को बदलने के लिए `.sqlite` फ़ाइल अपलोड करें। एक पूर्व-आयात बैकअप स्वचालित रूप से बनाया जाता है | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | -**आयात सत्यापन:** आयातित फ़ाइल को अखंडता (SQLite प्राग्मा चेक), आवश्यक तालिकाओं (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), और आकार (अधिकतम 100MB) के लिए मान्य किया गया है। +```bash +# API: Export database +curl -o backup.sqlite http://localhost:20128/api/db-backups/export -**उपयोग के मामले:** +# API: Export all (full archive) +curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll -- मशीनों के बीच ओम्निरूट माइग्रेट करें -- आपदा पुनर्प्राप्ति के लिए बाहरी बैकअप बनाएं -- टीम के सदस्यों के बीच कॉन्फ़िगरेशन साझा करें (सभी निर्यात करें → संग्रह साझा करें) +# API: Import database +curl -X POST http://localhost:20128/api/db-backups/import \ + -F "file=@backup.sqlite" +``` + +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). + +**Use Cases:** + +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### सेटिंग्स डैशबोर्ड +### Settings Dashboard -आसान नेविगेशन के लिए सेटिंग पृष्ठ को 5 टैब में व्यवस्थित किया गया है: +The settings page is organized into 5 tabs for easy navigation: -| टैब | सामग्री | -| ----------- | --------------------------------------------------------------------------------------------------- | -| **सुरक्षा** | लॉगिन/पासवर्ड सेटिंग्स, आईपी एक्सेस कंट्रोल, `/models` के लिए एपीआई प्रमाणीकरण, और प्रदाता ब्लॉकिंग | -| **रूटिंग** | वैश्विक रूटिंग रणनीति (6 विकल्प), वाइल्डकार्ड मॉडल उपनाम, फ़ॉलबैक चेन, कॉम्बो डिफ़ॉल्ट | -| **लचीलापन** | प्रदाता प्रोफाइल, संपादन योग्य दर सीमा, सर्किट ब्रेकर स्थिति, नीतियां और लॉक पहचानकर्ता | -| **एआई** | बजट कॉन्फ़िगरेशन, ग्लोबल सिस्टम प्रॉम्प्ट इंजेक्शन, प्रॉम्प्ट कैश आँकड़े सोचना | -| **उन्नत** | वैश्विक प्रॉक्सी कॉन्फ़िगरेशन (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### लागत एवं बजट प्रबंधन +### Costs & Budget Management -**डैशबोर्ड → लागत** के माध्यम से पहुंच। +Access via **Dashboard → Costs**. -| टैब | उद्देश्य | -| ------------------ | --------------------------------------------------------------------------------------------------------- | -| **बजट** | दैनिक/साप्ताहिक/मासिक बजट और वास्तविक समय ट्रैकिंग के साथ प्रति एपीआई कुंजी खर्च सीमा निर्धारित करें | -| **मूल्य निर्धारण** | मॉडल मूल्य निर्धारण प्रविष्टियाँ देखें और संपादित करें - प्रति प्रदाता प्रति 1K इनपुट/आउटपुट टोकन की लागत | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -458,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**लागत ट्रैकिंग:** प्रत्येक अनुरोध टोकन उपयोग को लॉग करता है और मूल्य निर्धारण तालिका का उपयोग करके लागत की गणना करता है। प्रदाता, मॉडल और एपीआई कुंजी द्वारा **डैशबोर्ड → उपयोग** में विश्लेषण देखें। +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### ऑडियो ट्रांसक्रिप्शन +### Audio Transcription -ओमनीरूट ओपनएआई-संगत एंडपॉइंट के माध्यम से ऑडियो ट्रांसक्रिप्शन का समर्थन करता है: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -478,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -उपलब्ध प्रदाता: **डीपग्राम** (`deepgram/`), **AssemblyAI** (`assemblyai/`)। +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -समर्थित ऑडियो प्रारूप: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`। +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### कॉम्बो संतुलन रणनीतियाँ +### Combo Balancing Strategies -**डैशबोर्ड → कॉम्बो → बनाएं/संपादित करें → रणनीति** में प्रति-कॉम्बो संतुलन कॉन्फ़िगर करें। +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| रणनीति | विवरण | -| --------------------- | ------------------------------------------------------------------------------ | -| **राउंड-रॉबिन** | मॉडलों के माध्यम से क्रमिक रूप से घूमता है | -| **प्राथमिकता** | हमेशा पहला मॉडल आज़माता है; केवल त्रुटि पर वापस आता है | -| **यादृच्छिक** | प्रत्येक अनुरोध के लिए कॉम्बो से एक यादृच्छिक मॉडल चुनता है | -| **भारित** | प्रति मॉडल निर्दिष्ट भार के आधार पर आनुपातिक रूप से मार्ग | -| **कम से कम इस्तेमाल** | सबसे कम हालिया अनुरोधों के साथ मॉडल पर रूट (कॉम्बो मेट्रिक्स का उपयोग करता है) | -| **लागत-अनुकूलित** | सबसे सस्ते उपलब्ध मॉडल के लिए मार्ग (मूल्य निर्धारण तालिका का उपयोग करता है) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -ग्लोबल कॉम्बो डिफॉल्ट्स को **डैशबोर्ड → सेटिंग्स → रूटिंग → कॉम्बो डिफॉल्ट्स** में सेट किया जा सकता है। +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### स्वास्थ्य डैशबोर्ड +### Health Dashboard -**डैशबोर्ड → स्वास्थ्य** के माध्यम से पहुंच। 6 कार्डों के साथ वास्तविक समय प्रणाली स्वास्थ्य अवलोकन: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| कार्ड | यह क्या दिखाता है | -| ---------------------- | ----------------------------------------------------------------------- | -| **सिस्टम स्थिति** | अपटाइम, संस्करण, मेमोरी उपयोग, डेटा निर्देशिका | -| **प्रदाता स्वास्थ्य** | प्रति-प्रदाता सर्किट ब्रेकर स्थिति (बंद/खुला/आधा-खुला) | -| **दर सीमा** | शेष समय के साथ प्रति खाता सक्रिय दर सीमा को शांत करना | -| **सक्रिय तालाबंदी** | प्रदाताओं को तालाबंदी नीति द्वारा अस्थायी रूप से अवरुद्ध कर दिया गया है | -| **हस्ताक्षर कैश** | डिडुप्लीकेशन कैश आँकड़े (सक्रिय कुंजियाँ, हिट दर) | -| **विलंबता टेलीमेट्री** | प्रति प्रदाता p50/p95/p99 विलंबता एकत्रीकरण | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**प्रो टिप:** स्वास्थ्य पृष्ठ हर 10 सेकंड में स्वतः ताज़ा हो जाता है। यह पहचानने के लिए सर्किट ब्रेकर कार्ड का उपयोग करें कि कौन से प्रदाता समस्याओं का सामना कर रहे हैं। +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/it/API_REFERENCE.md b/docs/i18n/it/API_REFERENCE.md index 488be267bf..b795722c11 100644 --- a/docs/i18n/it/API_REFERENCE.md +++ b/docs/i18n/it/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Riferimento API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Riferimento completo per tutti gli endpoint API OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Sommario +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Riferimento completo per tutti gli endpoint API OmniRoute. --- -## Completamenti della chat +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Intestazioni personalizzate +### Custom Headers -| Intestazione | Direzione | Descrizione | -| ------------------------ | --------- | --------------------------------------------------- | -| `X-OmniRoute-No-Cache` | Richiedi | Imposta su `true` per ignorare la cache | -| `X-OmniRoute-Progress` | Richiedi | Imposta su `true` per gli eventi di avanzamento | -| `Idempotency-Key` | Richiedi | Chiave di deduplicazione (finestra 5s) | -| `X-Request-Id` | Richiedi | Chiave di deduplicazione alternativa | -| `X-OmniRoute-Cache` | Risposta | `HIT` o `MISS` (non streaming) | -| `X-OmniRoute-Idempotent` | Risposta | `true` se deduplicato | -| `X-OmniRoute-Progress` | Risposta | `enabled` se il monitoraggio dei progressi è attivo | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Incorporamenti +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Fornitori disponibili: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Generazione di immagini +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Fornitori disponibili: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Elenco modelli +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Endpoint di compatibilità +## Compatibility Endpoints -| Metodo | Percorso | Formato | -| ------- | --------------------------- | ----------------------- | -| POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Antropico | -| POST | `/v1/responses` | Risposte OpenAI | -| POST | `/v1/embeddings` | OpenAI | -| POST | `/v1/images/generations` | OpenAI | -| OTTIENI | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Antropico | -| OTTIENI | `/v1beta/models` | Gemelli | -| POST | `/v1beta/models/{...path}` | Gemini genera contenuto | -| POST | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Percorsi di provider dedicati +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Se mancante, il prefisso del provider viene aggiunto automaticamente. I modelli non corrispondenti restituiscono `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Cache semantica +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Esempio di risposta: +Response example: ```json { @@ -162,154 +162,164 @@ Esempio di risposta: --- -## Cruscotto e gestione +## Dashboard & Management -### Autenticazione +### Authentication -| Punto finale | Metodo | Descrizione | -| ----------------------------- | ------------- | ----------------------------------- | -| `/api/auth/login` | POST | Accedi | -| `/api/auth/logout` | POST | Esci | -| `/api/settings/require-login` | OTTIENI/METTI | Attiva/disattiva il login richiesto | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Gestione dei fornitori +### Provider Management -| Punto finale | Metodo | Descrizione | -| ---------------------------- | ------------------------- | ---------------------------------------- | -| `/api/providers` | OTTIENI/POSTA | Elenca/crea fornitori | -| `/api/providers/[id]` | OTTIENI/INSERISCI/ELIMINA | Gestisci un fornitore | -| `/api/providers/[id]/test` | POST | Testare la connessione al provider | -| `/api/providers/[id]/models` | OTTIENI | Elenco modelli provider | -| `/api/providers/validate` | POST | Convalida la configurazione del provider | -| `/api/provider-nodes*` | Vari | Gestione nodo provider | -| `/api/provider-models` | OTTIENI/INVIA/ELIMINA | Modelli personalizzati | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Flussi OAuth +### OAuth Flows -| Punto finale | Metodo | Descrizione | -| -------------------------------- | ------ | ---------------------------- | -| `/api/oauth/[provider]/[action]` | Vari | OAuth specifico del provider | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Routing e configurazione +### Routing & Config -| Punto finale | Metodo | Descrizione | -| --------------------- | ------------- | ------------------------------------ | -| `/api/models/alias` | OTTIENI/POSTA | Alias ​​del modello | -| `/api/models/catalog` | OTTIENI | Tutti i modelli per fornitore + tipo | -| `/api/combos*` | Vari | Gestione combinata | -| `/api/keys*` | Vari | Gestione delle chiavi API | -| `/api/pricing` | OTTIENI | Prezzo del modello | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Utilizzo e analisi +### Usage & Analytics -| Punto finale | Metodo | Descrizione | -| --------------------------- | ------- | ------------------------------- | -| `/api/usage/history` | OTTIENI | Cronologia utilizzo | -| `/api/usage/logs` | OTTIENI | Registri di utilizzo | -| `/api/usage/request-logs` | OTTIENI | Registri a livello di richiesta | -| `/api/usage/[connectionId]` | OTTIENI | Utilizzo per connessione | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Impostazioni +### Settings -| Punto finale | Metodo | Descrizione | -| ------------------------------- | ------------- | ---------------------------------- | -| `/api/settings` | OTTIENI/METTI | Impostazioni generali | -| `/api/settings/proxy` | OTTIENI/METTI | Configurazione proxy di rete | -| `/api/settings/proxy/test` | POST | Testare la connessione proxy | -| `/api/settings/ip-filter` | OTTIENI/METTI | Lista consentita/lista bloccata IP | -| `/api/settings/thinking-budget` | OTTIENI/METTI | Ragionamento gettone bilancio | -| `/api/settings/system-prompt` | OTTIENI/METTI | Prompt del sistema globale | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Monitoraggio +### Monitoring -| Punto finale | Metodo | Descrizione | -| ------------------------ | --------------- | ---------------------------------- | -| `/api/sessions` | OTTIENI | Monitoraggio della sessione attiva | -| `/api/rate-limits` | OTTIENI | Limiti di tasso per conto | -| `/api/monitoring/health` | OTTIENI | Controllo sanitario | -| `/api/cache` | OTTIENI/ELIMINA | Statistiche cache / cancella | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Backup ed esportazione/importazione +### Backup & Export/Import -| Punto finale | Metodo | Descrizione | -| --------------------------- | ------- | ------------------------------------------------- | -| `/api/db-backups` | OTTIENI | Elenca i backup disponibili | -| `/api/db-backups` | METTERE | Crea un backup manuale | -| `/api/db-backups` | POST | Ripristina da un backup specifico | -| `/api/db-backups/export` | OTTIENI | Scarica il database come file .sqlite | -| `/api/db-backups/import` | POST | Carica il file .sqlite per sostituire il database | -| `/api/db-backups/exportAll` | OTTIENI | Scarica il backup completo come archivio .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Sincronizzazione nel cloud +### Cloud Sync -| Punto finale | Metodo | Descrizione | -| ---------------------- | ------ | ---------------------------------------- | -| `/api/sync/cloud` | Vari | Operazioni di sincronizzazione nel cloud | -| `/api/sync/initialize` | POST | Inizializza sincronizzazione | -| `/api/cloud/*` | Vari | Gestione del cloud | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Strumenti CLI +### CLI Tools -| Punto finale | Metodo | Descrizione | -| ---------------------------------- | ------- | --------------------------- | -| `/api/cli-tools/claude-settings` | OTTIENI | Stato CLI di Claude | -| `/api/cli-tools/codex-settings` | OTTIENI | Stato CLI del Codice | -| `/api/cli-tools/droid-settings` | OTTIENI | Stato CLI Droid | -| `/api/cli-tools/openclaw-settings` | OTTIENI | Stato della CLI di OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | OTTIENI | Runtime CLI generico | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Le risposte della CLI includono: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Resilienza e limiti di velocità +### ACP Agents -| Punto finale | Metodo | Descrizione | -| ----------------------- | ------------- | -------------------------------------------- | -| `/api/resilience` | OTTIENI/METTI | Ottieni/aggiorna profili di resilienza | -| `/api/resilience/reset` | POST | Ripristinare gli interruttori automatici | -| `/api/rate-limits` | OTTIENI | Stato limite tariffa per account | -| `/api/rate-limit` | OTTIENI | Configurazione del limite tariffario globale | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Valutazioni +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Punto finale | Metodo | Descrizione | -| ------------ | ------------- | ------------------------------------------------------ | -| `/api/evals` | OTTIENI/POSTA | Elenca le suite di valutazione / esegui la valutazione | +### Resilience & Rate Limits -### Politiche +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Punto finale | Metodo | Descrizione | -| --------------- | --------------------- | ------------------------------- | -| `/api/policies` | OTTIENI/INVIA/ELIMINA | Gestire le politiche di routing | +### Evals -### Conformità +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Punto finale | Metodo | Descrizione | -| --------------------------- | ------- | ------------------------------------------------- | -| `/api/compliance/audit-log` | OTTIENI | Registro di controllo della conformità (ultimi N) | +### Policies -### v1beta (compatibile con Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Punto finale | Metodo | Descrizione | -| -------------------------- | ------- | -------------------------------------- | -| `/v1beta/models` | OTTIENI | Elenco modelli in formato Gemini | -| `/v1beta/models/{...path}` | POST | Gemelli `generateContent` punto finale | +### Compliance -Questi endpoint rispecchiano il formato API di Gemini per i client che prevedono la compatibilità nativa dell'SDK Gemini. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### API interne/di sistema +### v1beta (Gemini-Compatible) -| Punto finale | Metodo | Descrizione | -| --------------- | ------- | ------------------------------------------------------------------------------------ | -| `/api/init` | OTTIENI | Controllo dell'inizializzazione dell'applicazione (utilizzato alla prima esecuzione) | -| `/api/tags` | OTTIENI | Tag modello compatibili con Ollama (per client Ollama) | -| `/api/restart` | POST | Attiva il riavvio corretto del server | -| `/api/shutdown` | POST | Attiva l'arresto regolare del server | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Nota:** questi endpoint vengono utilizzati internamente dal sistema o per la compatibilità del client Ollama. In genere non vengono chiamati dagli utenti finali. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Trascrizione audio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Trascrivi file audio utilizzando Deepgram o AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Richiesta:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Risposta:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Fornitori supportati:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Formati supportati:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Compatibilità con Ollama +## Ollama Compatibility -Per i clienti che utilizzano il formato API di Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Le richieste vengono tradotte automaticamente tra Ollama e formati interni. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetria +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Risposta:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Bilancio +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Disponibilità del modello +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Elaborazione della richiesta +## Request Processing -1. Il cliente invia la richiesta a `/v1/*` -2. Chiamate del gestore del percorso `handleChat`, `handleEmbedding`, `handleAudioTranscription` o `handleImageGeneration` -3. Il modello è risolto (provider/modello diretto o alias/combo) -4. Credenziali selezionate dal DB locale con filtro sulla disponibilità dell'account -5. Per chat: `handleChatCore`: rilevamento del formato, traduzione, controllo della cache, controllo dell'idempotenza -6. L'esecutore del provider invia una richiesta upstream -7. Risposta ricondotta nel formato client (chat) o restituita così com'è (incorporamenti/immagini/audio) -8. Utilizzo/registrazione registrati -9. Il fallback si applica agli errori secondo le regole della combo +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Riferimento completo all'architettura: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Autenticazione +## Authentication -- I percorsi della dashboard (`/dashboard/*`) utilizzano il cookie `auth_token` -- L'accesso utilizza l'hash della password salvata; fallback su `INITIAL_PASSWORD` -- `requireLogin` attivabile tramite `/api/settings/require-login` -- Le rotte `/v1/*` richiedono facoltativamente la chiave API Bearer quando `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/it/ARCHITECTURE.md b/docs/i18n/it/ARCHITECTURE.md index 2d42cb82f6..258d62df53 100644 --- a/docs/i18n/it/ARCHITECTURE.md +++ b/docs/i18n/it/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Architettura OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Ultimo aggiornamento: 2026-02-18_ +_Last updated: 2026-03-04_ -## Sintesi +## Executive Summary -OmniRoute è un gateway di routing AI locale e un dashboard basato su Next.js. -Fornisce un singolo endpoint compatibile con OpenAI (`/v1/*`) e instrada il traffico attraverso più provider upstream con traduzione, fallback, aggiornamento dei token e monitoraggio dell'utilizzo. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Funzionalità principali: +Core capabilities: -- Superficie API compatibile con OpenAI per CLI/strumenti (28 provider) -- Traduzione di richieste/risposte tra formati di fornitori -- Fallback combo modello (sequenza multi-modello) -- Fallback a livello di account (più account per fornitore) -- Gestione della connessione del provider OAuth + chiave API -- Generazione di incorporamento tramite `/v1/embeddings` (6 fornitori, 9 modelli) -- Generazione di immagini tramite `/v1/images/generations` (4 fornitori, 9 modelli) -- Pensa all'analisi dei tag (`...`) per i modelli di ragionamento -- Sanificazione della risposta per una rigorosa compatibilità con l'SDK OpenAI -- Normalizzazione dei ruoli (sviluppatore→sistema, sistema→utente) per compatibilità tra provider -- Conversione dell'output strutturato (json_schema → Gemini ResponseSchema) -- Persistenza locale per provider, chiavi, alias, combo, impostazioni, prezzi -- Monitoraggio dell'utilizzo/costo e registrazione delle richieste -- Sincronizzazione cloud opzionale per la sincronizzazione multi-dispositivo/stato -- Lista consentita/lista bloccata IP per il controllo dell'accesso API -- Gestione intelligente del budget (passthrough/automatico/personalizzato/adattivo) -- Iniezione rapida del sistema globale -- Monitoraggio della sessione e rilevamento delle impronte digitali -- Limitazione tariffaria migliorata per account con profili specifici del fornitore -- Modello di interruttore automatico per la resilienza del fornitore -- Protezione gregge antituono con bloccaggio mutex -- Cache di deduplicazione delle richieste basata su firma -- Livello dominio: disponibilità del modello, regole di costo, politica di fallback, politica di blocco -- Persistenza dello stato del dominio (cache write-through SQLite per fallback, budget, blocchi, interruttori automatici) -- Motore di policy per la valutazione centralizzata delle richieste (blocco → budget → fallback) -- Richiedi telemetria con aggregazione della latenza p50/p95/p99 -- ID di correlazione (X-Request-Id) per la traccia end-to-end -- Registrazione del controllo di conformità con rinuncia per chiave API -- Quadro di valutazione per la garanzia della qualità LLM -- Dashboard dell'interfaccia utente di resilienza con stato dell'interruttore automatico in tempo reale -- Provider OAuth modulari (12 moduli individuali in `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Modello runtime primario: +Primary runtime model: -- I percorsi dell'app Next.js in `src/app/api/*` implementano sia le API del dashboard che le API di compatibilità -- Un core SSE/routing condiviso in `src/sse/*` + `open-sse/*` gestisce l'esecuzione, la traduzione, lo streaming, il fallback e l'utilizzo del provider +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Ambito e confini +## Scope and Boundaries -### Nell'ambito +### In Scope -- Runtime del gateway locale -- API di gestione della dashboard -- Autenticazione del provider e aggiornamento del token -- Richiedi traduzione e streaming SSE -- Stato locale + persistenza dell'utilizzo -- Orchestrazione opzionale della sincronizzazione cloud +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Fuori portata +### Out of Scope -- Implementazione del servizio cloud dietro `NEXT_PUBLIC_CLOUD_URL` -- SLA/piano di controllo del fornitore esterno al processo locale -- Gli stessi binari CLI esterni (Claude CLI, Codex CLI, ecc.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Contesto del sistema di alto livello +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Componenti runtime principali +## Core Runtime Components -## 1) API e livello di routing (percorsi dell'app Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Directory principali: +Main directories: -- `src/app/api/v1/*` e `src/app/api/v1beta/*` per API di compatibilità -- `src/app/api/*` per le API di gestione/configurazione -- Successivamente riscrive nella mappa `next.config.mjs` `/v1/*` in `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Percorsi di compatibilità importanti: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts`: include modelli personalizzati con `custom: true` -- `src/app/api/v1/embeddings/route.ts`: generazione di incorporamenti (6 fornitori) -- `src/app/api/v1/images/generations/route.ts` — generazione di immagini (4+ fornitori incluso Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts`: chat dedicata per provider -- `src/app/api/v1/providers/[provider]/embeddings/route.ts`: incorporamenti dedicati per provider -- `src/app/api/v1/providers/[provider]/images/generations/route.ts`: immagini dedicate per provider +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Domini di gestione: +Management domains: -- Autenticazione/impostazioni: `src/app/api/auth/*`, `src/app/api/settings/*` -- Provider/connessioni: `src/app/api/providers*` -- Nodi fornitore: `src/app/api/provider-nodes*` -- Modelli personalizzati: `src/app/api/provider-models` (GET/POST/DELETE) -- Catalogo modelli: `src/app/api/models/catalog` (OTTIENI) -- Configurazione proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Chiavi/alias/combo/prezzi: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Utilizzo: `src/app/api/usage/*` -- Sincronizzazione/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Aiutanti degli strumenti CLI: `src/app/api/cli-tools/*` -- Filtro IP: `src/app/api/settings/ip-filter` (GET/PUT) -- Budget pensato: `src/app/api/settings/thinking-budget` (GET/PUT) -- Richiesta di sistema: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessioni: `src/app/api/sessions` (GET) -- Limiti di velocità: `src/app/api/rate-limits` (GET) -- Resilienza: `src/app/api/resilience` (GET/PATCH): profili dei fornitori, interruttore automatico, stato limite di velocità -- Ripristino della resilienza: `src/app/api/resilience/reset` (POST): ripristina gli interruttori + tempi di recupero -- Statistiche cache: `src/app/api/cache/stats` (OTTIENI/ELIMINA) -- Disponibilità del modello: `src/app/api/models/availability` (GET/POST) -- Telemetria: `src/app/api/telemetry/summary` (OTTIENI) -- Budget: `src/app/api/usage/budget` (OTTIENI/POST) -- Catene di fallback: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Controllo di conformità: `src/app/api/compliance/audit-log` (GET) -- Valutazioni: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Politiche: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Nucleo di traduzione +## 2) SSE + Translation Core -Principali moduli di flusso: +Main flow modules: -- Voce: `src/sse/handlers/chat.ts` -- Orchestrazione principale: `open-sse/handlers/chatCore.ts` -- Adattatori di esecuzione del provider: `open-sse/executors/*` -- Rilevamento formato/configurazione provider: `open-sse/services/provider.ts` -- Analisi/risoluzione del modello: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Logica di fallback dell'account: `open-sse/services/accountFallback.ts` -- Registro delle traduzioni: `open-sse/translator/index.ts` -- Trasformazioni del flusso: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Estrazione/normalizzazione dell'utilizzo: `open-sse/utils/usageTracking.ts` -- Pensa al parser dei tag: `open-sse/utils/thinkTagParser.ts` -- Gestore di incorporamento: `open-sse/handlers/embeddings.ts` -- Incorporamento del registro dei provider: `open-sse/config/embeddingRegistry.ts` -- Gestore di generazione di immagini: `open-sse/handlers/imageGeneration.ts` -- Registro del fornitore di immagini: `open-sse/config/imageRegistry.ts` -- Sanificazione della risposta: `open-sse/handlers/responseSanitizer.ts` -- Normalizzazione del ruolo: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Servizi (logica aziendale): +Services (business logic): -- Selezione/punteggio dell'account: `open-sse/services/accountSelector.ts` -- Gestione del ciclo di vita del contesto: `open-sse/services/contextManager.ts` -- Applicazione del filtro IP: `open-sse/services/ipFilter.ts` -- Monitoraggio della sessione: `open-sse/services/sessionManager.ts` -- Richiedi deduplicazione: `open-sse/services/signatureCache.ts` -- Inserimento prompt del sistema: `open-sse/services/systemPrompt.ts` -- Gestione intelligente del budget: `open-sse/services/thinkingBudget.ts` -- Routing del modello con caratteri jolly: `open-sse/services/wildcardRouter.ts` -- Gestione dei limiti di velocità: `open-sse/services/rateLimitManager.ts` -- Interruttore automatico: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Moduli del livello di dominio: +Domain layer modules: -- Disponibilità del modello: `src/lib/domain/modelAvailability.ts` -- Regole di costo/budget: `src/lib/domain/costRules.ts` -- Politica di riserva: `src/lib/domain/fallbackPolicy.ts` -- Risolutore combinato: `src/lib/domain/comboResolver.ts` -- Politica di blocco: `src/lib/domain/lockoutPolicy.ts` -- Motore delle politiche: `src/domain/policyEngine.ts` — blocco centralizzato → budget → valutazione fallback -- Catalogo codici errore: `src/lib/domain/errorCodes.ts` -- ID richiesta: `src/lib/domain/requestId.ts` -- Timeout recupero: `src/lib/domain/fetchTimeout.ts` -- Richiedi telemetria: `src/lib/domain/requestTelemetry.ts` -- Conformità/controllo: `src/lib/domain/compliance/index.ts` -- Corridore di valutazione: `src/lib/domain/evalRunner.ts` -- Persistenza dello stato del dominio: `src/lib/db/domainState.ts` — SQLite CRUD per catene di fallback, budget, cronologia dei costi, stato di blocco, interruttori automatici +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Moduli provider OAuth (12 file singoli in `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Indice del registro: `src/lib/oauth/providers/index.ts` -- Singoli fornitori: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Involucro sottile: `src/lib/oauth/providers.ts` — riesporta da singoli moduli +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Livello di persistenza +## 3) Persistence Layer -DB di stato primario: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- file: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` quando impostato, altrimenti `~/.omniroute/db.json`) -- entità: providerConnections, providerNodes, modelAliases, combo, apiKeys, impostazioni, prezzi, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -DB di utilizzo: +Usage persistence: -- `src/lib/usageDb.ts` -- file: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- segue la stessa policy di directory di base di `localDb` (`DATA_DIR`, quindi `XDG_CONFIG_HOME/omniroute` quando impostato) -- scomposto in sottomoduli focalizzati: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -DB dello stato del dominio (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts`: operazioni CRUD per lo stato del dominio -- Tabelle (create in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Schema cache write-through: le mappe in memoria sono autorevoli in fase di esecuzione; le mutazioni vengono scritte in modo sincrono su SQLite; lo stato viene ripristinato dal DB all'avvio a freddo +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Superfici di autenticazione e sicurezza +## 4) Auth + Security Surfaces -- Autenticazione cookie dashboard: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Generazione/verifica della chiave API: `src/shared/utils/apiKey.ts` -- I segreti del provider sono persistenti nelle voci `providerConnections` -- Supporto proxy in uscita tramite `open-sse/utils/proxyFetch.ts` (env vars) e `open-sse/utils/networkProxy.ts` (configurabile per provider o globale) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Sincronizzazione nel cloud +## 5) Cloud Sync -- Inizializzazione pianificazione: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Attività periodica: `src/shared/services/cloudSyncScheduler.ts` -- Percorso di controllo: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Ciclo di vita della richiesta (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Flusso di fallback dell'account +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Le decisioni di fallback sono guidate da `open-sse/services/accountFallback.ts` utilizzando codici di stato ed euristica dei messaggi di errore. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Ciclo di vita dell'onboarding OAuth e dell'aggiornamento dei token +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -L'aggiornamento durante il traffico in tempo reale viene eseguito all'interno di `open-sse/handlers/chatCore.ts` tramite l'esecutore `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Ciclo di vita della sincronizzazione cloud (Abilita/Sincronizza/Disabilita) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -La sincronizzazione periodica viene attivata da `CloudSyncScheduler` quando il cloud è abilitato. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Modello dei dati e mappa di archiviazione +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -File di archiviazione fisica: +Physical storage files: -- stato principale: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` quando impostato, altrimenti `~/.omniroute/db.json`) -- statistiche di utilizzo: `${DATA_DIR}/usage.json` -- righe di registro della richiesta: `${DATA_DIR}/log.txt` -- sessioni di debug traduttore/richiesta opzionali: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topologia di distribuzione +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Mappatura dei moduli (critica per la decisione) +## Module Mapping (Decision-Critical) -### Itinerario e moduli API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API di compatibilità -- `src/app/api/v1/providers/[provider]/*`: percorsi dedicati per provider (chat, incorporamenti, immagini) -- `src/app/api/providers*`: CRUD del fornitore, convalida, test -- `src/app/api/provider-nodes*`: gestione personalizzata dei nodi compatibili -- `src/app/api/provider-models`: gestione del modello personalizzato (CRUD) -- `src/app/api/models/catalog`: API del catalogo modelli completo (tutti i tipi raggruppati per fornitore) -- `src/app/api/oauth/*`: flussi OAuth/codice dispositivo -- `src/app/api/keys*`: ciclo di vita della chiave API locale -- `src/app/api/models/alias`: gestione alias -- `src/app/api/combos*`: gestione combo fallback -- `src/app/api/pricing`: il prezzo sostituisce il calcolo dei costi -- `src/app/api/settings/proxy`: configurazione proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: test di connettività proxy in uscita (POST) -- `src/app/api/usage/*`: API di utilizzo e log -- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronizzazione cloud e aiutanti rivolti al cloud -- `src/app/api/cli-tools/*`: scrittori/controllori di configurazione CLI locale -- `src/app/api/settings/ip-filter`: lista consentita/lista bloccata IP (GET/PUT) -- `src/app/api/settings/thinking-budget`: configurazione del budget del token pensante (GET/PUT) -- `src/app/api/settings/system-prompt`: prompt di sistema globale (GET/PUT) -- `src/app/api/sessions`: elenco sessioni attive (GET) -- `src/app/api/rate-limits`: stato limite tariffa per account (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Nucleo di routing ed esecuzione +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: analisi delle richieste, gestione delle combo, ciclo di selezione dell'account -- `open-sse/handlers/chatCore.ts`: traduzione, invio dell'esecutore, gestione di nuovi tentativi/aggiornamenti, impostazione del flusso -- `open-sse/executors/*`: comportamento di rete e formato specifico del provider +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Registro di traduzione e convertitori di formato +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: registro e orchestrazione dei traduttori -- Richiedi traduttori: `open-sse/translator/request/*` -- Traduttori di risposta: `open-sse/translator/response/*` -- Costanti di formato: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Persistenza +### Persistence -- `src/lib/localDb.ts`: configurazione/stato persistente -- `src/lib/usageDb.ts`: cronologia di utilizzo e registri delle richieste in sequenza +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Copertura dell'esecutore del provider (modello strategico) +## Provider Executor Coverage (Strategy Pattern) -Ogni provider dispone di un esecutore specializzato che estende `BaseExecutor` (in `open-sse/executors/base.ts`), che fornisce la creazione di URL, la costruzione di intestazioni, nuovi tentativi con backoff esponenziale, hook di aggiornamento delle credenziali e il metodo di orchestrazione `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Esecutore testamentario | Fornitore/i | Movimentazione speciale | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configurazione URL/intestazione dinamica per provider | -| `AntigravityExecutor` | Google Antigravità | ID progetto/sessione personalizzati, analisi Riprova dopo | -| `CodexExecutor` | Codice OpenAI | Inserisce istruzioni di sistema, forza lo sforzo di ragionamento | -| `CursorExecutor` | Cursore IDE | Protocollo ConnectRPC, codifica Protobuf, firma della richiesta tramite checksum | -| `GithubExecutor` | Copilota GitHub | Aggiornamento del token Copilot, intestazioni che imitano VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binario AWS EventStream → conversione SSE | -| `GeminiCLIExecutor` | Gemelli CLI | Ciclo di aggiornamento del token OAuth di Google | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Tutti gli altri provider (inclusi i nodi compatibili personalizzati) utilizzano `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matrice di compatibilità del fornitore +## Provider Compatibility Matrix -| Fornitore | Formato | Aut. | Flusso | Non streaming | Aggiornamento token | API di utilizzo | -| --------------------- | --------------- | ----------------------- | ---------------- | ------------- | ------------------- | ------------------------ | -| Claudio | claude | Chiave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Solo amministratore | -| Gemelli | gemelli | Chiave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Console cloud | -| Gemelli CLI | gemelli-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Console cloud | -| Antigravità | antigravità | OAuth | ✅ | ✅ | ✅ | ✅ API quota completa | -| OpenAI | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| Codice | risposte-openai | OAuth | ✅ forzato | ❌ | ✅ | ✅ Limiti tariffari | -| Copilota GitHub | openai | OAuth + token copilota | ✅ | ✅ | ✅ | ✅Istantanee delle quote | -| Cursore | cursore | Checksum personalizzato | ✅ | ✅ | ❌ | ❌ | -| Kiro | Kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limiti di utilizzo | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Su richiesta | -| iFlow | openai | OAuth (base) | ✅ | ✅ | ✅ | ⚠️ Su richiesta | -| OpenRouter | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | Chiave API | ✅ | ✅ | ❌ | ❌ | -| Ricerca profonda | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| Maestrale | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| Perplessità | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| Insieme AI | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| Fuochi d'artificio AI | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| Cerebri | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| Coerenza | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Copertura della traduzione del formato +## Format Translation Coverage -I formati sorgente rilevati includono: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -I formati di destinazione includono: +Target formats include: -- Chat/risposte OpenAI -- Claudio -- Busta Gemini/Gemini-CLI/Antigravità +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Cursore +- Cursor -Le traduzioni utilizzano **OpenAI come formato hub**: tutte le conversioni passano attraverso OpenAI come formato intermedio: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Le traduzioni vengono selezionate dinamicamente in base alla forma del payload di origine e al formato di destinazione del provider. +Translations are selected dynamically based on source payload shape and provider target format. -Ulteriori livelli di elaborazione nella pipeline di traduzione: +Additional processing layers in the translation pipeline: -- **Sanificazione delle risposte**: rimuove i campi non standard dalle risposte in formato OpenAI (sia in streaming che non in streaming) per garantire la rigorosa conformità dell'SDK -- **Normalizzazione del ruolo**: converte `developer` → `system` per target non OpenAI; unisce `system` → `user` per i modelli che rifiutano il ruolo di sistema (GLM, ERNIE) -- **Estrazione tag Think**: analizza i blocchi `...` dal contenuto nel campo `reasoning_content` -- **Output strutturato**: converte OpenAI `response_format.json_schema` in `responseMimeType` di Gemini + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Endpoint API supportati +## Supported API Endpoints -| Punto finale | Formato | Gestore | -| -------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------ | -| `POST /v1/chat/completions` | Chatta OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Messaggi di Claude | Stesso gestore (rilevato automaticamente) | -| `POST /v1/responses` | Risposte OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Incorporamenti OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Elenco dei modelli | Percorso API | -| `POST /v1/images/generations` | Immagini OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Elenco dei modelli | Percorso API | -| `POST /v1/providers/{provider}/chat/completions` | Chatta OpenAI | Dedicato per provider con convalida del modello | -| `POST /v1/providers/{provider}/embeddings` | Incorporamenti OpenAI | Dedicato per provider con convalida del modello | -| `POST /v1/providers/{provider}/images/generations` | Immagini OpenAI | Dedicato per provider con convalida del modello | -| `POST /v1/messages/count_tokens` | Conteggio gettoni Claude | Percorso API | -| `GET /v1/models` | Elenco modelli OpenAI | Percorso API (chat + incorporamento + immagine + modelli personalizzati) | -| `GET /api/models/catalog` | Catalogo | Tutti i modelli raggruppati per fornitore + tipo | -| `POST /v1beta/models/*:streamGenerateContent` | Nativo dei Gemelli | Percorso API | -| `GET/PUT/DELETE /api/settings/proxy` | Configurazione proxy | Configurazione proxy di rete | -| `POST /api/settings/proxy/test` | Connettività proxy | Endpoint di test di integrità/connettività proxy | -| `GET/POST/DELETE /api/provider-models` | Modelli personalizzati | Gestione modelli personalizzati per fornitore | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Gestore di bypass +## Bypass Handler -Il gestore di bypass (`open-sse/utils/bypassHandler.ts`) intercetta le richieste "usa e getta" note dalla CLI di Claude (ping di riscaldamento, estrazioni di titoli e conteggi di token) e restituisce una **risposta falsa** senza consumare token del provider upstream. Questo viene attivato solo quando `User-Agent` contiene `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Richiedi la pipeline del registratore +## Request Logger Pipeline -Il logger delle richieste (`open-sse/utils/requestLogger.ts`) fornisce una pipeline di registrazione del debug in 7 fasi, disabilitata per impostazione predefinita, abilitata tramite `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -I file vengono scritti in `/logs//` per ogni sessione di richiesta. +Files are written to `/logs//` for each request session. -## Modalità di fallimento e resilienza +## Failure Modes and Resilience -## 1) Disponibilità dell'account/fornitore +## 1) Account/Provider Availability -- Tempo di recupero dell'account del provider in caso di errori temporanei/velocità/autenticazione -- fallback dell'account prima di fallire la richiesta -- fallback del modello combinato quando il percorso del modello/provider corrente è esaurito +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Scadenza del token +## 2) Token Expiry -- controllo preliminare e aggiornamento con nuovo tentativo per i provider aggiornabili -- Nuovo tentativo 401/403 dopo il tentativo di aggiornamento nel percorso principale +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Sicurezza dello streaming +## 3) Stream Safety -- controller di flusso in grado di riconoscere la disconnessione -- flusso di traduzione con scarico di fine flusso e gestione `[DONE]` -- fallback della stima dell'utilizzo quando mancano i metadati di utilizzo del provider +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Degrado della sincronizzazione cloud +## 4) Cloud Sync Degradation -- Sono emersi errori di sincronizzazione ma il runtime locale continua -- Lo scheduler ha una logica che consente di riprovare, ma l'esecuzione periodica attualmente chiama la sincronizzazione a tentativo singolo per impostazione predefinita +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integrità dei dati +## 5) Data Integrity -- Migrazione/riparazione della forma DB per chiavi mancanti -- protezioni di reimpostazione JSON corrotte per localDb e UsageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Osservabilità e segnali operativi +## Observability and Operational Signals -Origini della visibilità in runtime: +Runtime visibility sources: -- registri della console da `src/sse/utils/logger.ts` -- aggregati di utilizzo per richiesta in `usage.json` -- accesso testuale sullo stato della richiesta `log.txt` -- log di richiesta/traduzione approfonditi opzionali in `logs/` quando `ENABLE_REQUEST_LOGS=true` -- Endpoint di utilizzo del dashboard (`/api/usage/*`) per il consumo dell'interfaccia utente +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Confini sensibili alla sicurezza +## Security-Sensitive Boundaries -- Il segreto JWT (`JWT_SECRET`) protegge la verifica/firma dei cookie della sessione del dashboard -- Il fallback della password iniziale (`INITIAL_PASSWORD`, predefinito `123456`) deve essere sovrascritto nelle distribuzioni reali -- Il segreto HMAC della chiave API (`API_KEY_SECRET`) protegge il formato della chiave API locale generata -- I segreti del provider (chiavi/token API) vengono mantenuti nel DB locale e devono essere protetti a livello di file system -- Gli endpoint di sincronizzazione cloud si basano sull'autenticazione della chiave API e sulla semantica dell'ID macchina +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Matrice di ambiente e runtime +## Environment and Runtime Matrix -Variabili d'ambiente utilizzate attivamente dal codice: +Environment variables actively used by code: -- App/autenticazione: `JWT_SECRET`, `INITIAL_PASSWORD` -- Spazio di archiviazione: `DATA_DIR` -- Comportamento del nodo compatibile: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Override opzionale della base di archiviazione (Linux/macOS quando `DATA_DIR` non impostato): `XDG_CONFIG_HOME` -- Hashing di sicurezza: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Registrazione: `ENABLE_REQUEST_LOGS` -- URL di sincronizzazione/cloud: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Proxy in uscita: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` e varianti minuscole -- Flag funzionalità SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Supporti piattaforma/runtime (non configurazione specifica dell'app): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Note architettoniche conosciute +## Known Architectural Notes -1. `usageDb` e `localDb` ora condividono la stessa policy di directory di base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) con la migrazione dei file legacy. -2. `/api/v1/route.ts` restituisce un elenco di modelli statici e non è la fonte principale dei modelli utilizzata da `/v1/models`. -3. Il registro delle richieste scrive intestazioni/corpo completi quando abilitato; considera la directory dei log come sensibile. -4. Il comportamento del cloud dipende dalla corretta `NEXT_PUBLIC_BASE_URL` e dalla raggiungibilità dell'endpoint cloud. -5. La directory `open-sse/` viene pubblicata come `@omniroute/open-sse` **pacchetto area di lavoro npm**. Il codice sorgente lo importa tramite `@omniroute/open-sse/...` (risolto da Next.js `transpilePackages`). I percorsi dei file in questo documento utilizzano ancora il nome della directory `open-sse/` per coerenza. -6. I grafici nel dashboard utilizzano **Recharts** (basati su SVG) per visualizzazioni analitiche accessibili e interattive (grafici a barre sull'utilizzo del modello, tabelle di suddivisione dei fornitori con percentuali di successo). -7. I test E2E utilizzano **Playwright** (`tests/e2e/`), eseguiti tramite `npm run test:e2e`. I test unitari utilizzano **Node.js test runner** (`tests/unit/`), eseguiti tramite `npm run test:plan3`. Il codice sorgente in `src/` è **TypeScript** (`.ts`/`.tsx`); l'area di lavoro `open-sse/` rimane JavaScript (`.js`). -8. La pagina Impostazioni è organizzata in 5 schede: Sicurezza, Routing (6 strategie globali: riempimento prima, round robin, p2c, casuale, meno utilizzato, ottimizzato in termini di costi), Resilienza (limiti di velocità modificabili, interruttore automatico, policy), AI (budget pensato, prompt di sistema, cache dei prompt), Avanzate (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Lista di controllo per la verifica operativa +## Operational Verification Checklist -- Costruisci dalla fonte: `npm run build` -- Crea immagine Docker: `docker build -t omniroute .` -- Avviare il servizio e verificare: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- L'URL di base di destinazione della CLI deve essere `http://:20128/v1` quando `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/it/CODEBASE_DOCUMENTATION.md b/docs/i18n/it/CODEBASE_DOCUMENTATION.md index f702ddd0b8..303880c198 100644 --- a/docs/i18n/it/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/it/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute: documentazione della base di codice +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Una guida completa e adatta ai principianti al router proxy AI multi-provider **omniroute**. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Che cos'è omniroute? +## 1. What Is omniroute? -omniroute è un **router proxy** che si trova tra i client AI (Claude CLI, Codex, Cursor IDE, ecc.) e i fornitori di AI (Anthropic, Google, OpenAI, AWS, GitHub, ecc.). Risolve un grosso problema: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Client IA diversi parlano "linguaggi" diversi (formati API) e anche fornitori di IA diversi si aspettano "linguaggi" diversi.** omniroute traduce automaticamente tra loro. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Pensatelo come un traduttore universale alle Nazioni Unite: qualsiasi delegato può parlare qualsiasi lingua e il traduttore la converte per qualsiasi altro delegato. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Panoramica dell'architettura +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Principio fondamentale: traduzione Hub-and-Spoke +### Core Principle: Hub-and-Spoke Translation -Tutte le traduzioni dei formati passano attraverso il **formato OpenAI come hub**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Ciò significa che hai bisogno solo di **N traduttori** (uno per formato) invece di **N²** (ogni coppia). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Struttura del progetto +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Analisi modulo per modulo +## 4. Module-by-Module Breakdown -### 4.1 Configurazione (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -L'**unica fonte di verità** per la configurazione di tutti i provider. +The **single source of truth** for all provider configuration. -| File | Scopo | -| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | Oggetto `PROVIDERS` con URL di base, credenziali OAuth (predefinite), intestazioni e prompt di sistema predefiniti per ogni provider. Definisce anche `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` e `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Carica le credenziali esterne da `data/provider-credentials.json` e le unisce alle impostazioni predefinite hardcoded in `PROVIDERS`. Mantiene i segreti fuori dal controllo del codice sorgente mantenendo la compatibilità con le versioni precedenti. | -| `providerModels.ts` | Registro centrale del modello: alias del fornitore delle mappe → ID del modello. Funzioni come `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Istruzioni di sistema inserite nelle richieste del Codex (vincoli di modifica, regole sandbox, politiche di approvazione). | -| `defaultThinkingSignature.ts` | Firme "pensanti" predefinite per i modelli Claude e Gemini. | -| `ollamaModels.ts` | Definizione di schemi per modelli Ollama locali (nome, dimensione, famiglia, quantizzazione). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Flusso di caricamento delle credenziali +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Esecutori (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Gli esecutori incapsulano la **logica specifica del provider** utilizzando il **Strategy Pattern**. Ogni esecutore sovrascrive i metodi di base secondo necessità. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Esecutore testamentario | Fornitore | Specializzazioni chiave | -| ----------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Base astratta: creazione di URL, intestazioni, logica dei tentativi, aggiornamento delle credenziali | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Aggiornamento del token OAuth generico per i provider standard | -| `antigravity.ts` | Codice Google Cloud | Generazione ID progetto/sessione, fallback multi-URL, nuovi tentativi di analisi personalizzati dai messaggi di errore ("reimposta dopo 2h7m23s") | -| `cursor.ts` | Cursore IDE | **Più complesso**: autenticazione checksum SHA-256, codifica della richiesta Protobuf, EventStream binario → Analisi della risposta SSE | -| `codex.ts` | Codice OpenAI | Inserisce istruzioni di sistema, gestisce i livelli di pensiero, rimuove i parametri non supportati | -| `gemini-cli.ts` | CLI di Google Gemini | Creazione di URL personalizzati (`streamGenerateContent`), aggiornamento del token OAuth di Google | -| `github.ts` | Copilota GitHub | Sistema a doppio token (GitHub OAuth + token Copilot), intestazione VSCode che imita | -| `kiro.ts` | AWS CodeWhisperer | Analisi binaria AWS EventStream, frame di eventi AMZN, stima dei token | -| `index.ts` | — | Fabbrica: nome del provider delle mappe → classe dell'esecutore, con fallback predefinito | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Gestori (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -Il **livello di orchestrazione**: coordina la traduzione, l'esecuzione, lo streaming e la gestione degli errori. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| File | Scopo | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Orchestratore centrale** (~600 linee). Gestisce il ciclo di vita completo della richiesta: rilevamento del formato → traduzione → invio dell'esecutore → risposta in streaming/non streaming → aggiornamento del token → gestione degli errori → registrazione dell'utilizzo. | -| `responsesHandler.ts` | Adattatore per l'API Responses di OpenAI: converte il formato delle risposte → Completamenti chat → invia a `chatCore` → riconverte SSE nel formato delle risposte. | -| `embeddings.ts` | Gestore della generazione di incorporamento: risolve il modello di incorporamento → provider, invia all'API del provider, restituisce una risposta di incorporamento compatibile con OpenAI. Supporta più di 6 fornitori. | -| `imageGeneration.ts` | Gestore di generazione di immagini: risolve il modello di immagine → provider, supporta le modalità compatibili con OpenAI, Gemini-image (Antigravity) e fallback (Nebius). Restituisce immagini base64 o URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Ciclo di vita della richiesta (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Servizi (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Logica di business che supporta i gestori e gli esecutori. +Business logic that supports the handlers and executors. -| File | Scopo | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `provider.ts` | **Rilevamento formato** (`detectFormat`): analizza la struttura del corpo della richiesta per identificare i formati Claude/OpenAI/Gemini/Antigravity/Responses (include l'euristica `max_tokens` per Claude). Inoltre: creazione di URL, creazione di intestazioni, normalizzazione della configurazione del pensiero. Supporta i provider dinamici `openai-compatible-*` e `anthropic-compatible-*`. | -| `model.ts` | Analisi delle stringhe del modello (`claude/model-name` → `{provider: "claude", model: "model-name"}`), risoluzione degli alias con rilevamento delle collisioni, sanificazione dell'input (rifiuta i caratteri di controllo/attraversamento del percorso) e risoluzione delle informazioni del modello con supporto getter di alias asincrono. | -| `accountFallback.ts` | Gestione dei limiti di velocità: backoff esponenziale (1s → 2s → 4s → max 2min), gestione del cooldown dell'account, classificazione degli errori (quali errori attivano il fallback e quali no). | -| `tokenRefresh.ts` | Aggiornamento del token OAuth per **ogni provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (doppio token OAuth + Copilot), Kiro (AWS SSO OIDC + Social Auth). Include cache di deduplicazione delle promesse in volo e tentativi con backoff esponenziale. | -| `combo.ts` | **Modelli combo**: catene di modelli fallback. Se il modello A fallisce con un errore idoneo al fallback, prova il modello B, poi C, ecc. Restituisce i codici di stato upstream effettivi. | -| `usage.ts` | Recupera i dati sulle quote/utilizzo dalle API del provider (quote GitHub Copilot, quote del modello Antigravity, limiti di velocità del Codex, suddivisioni sull'utilizzo di Kiro, impostazioni di Claude). | -| `accountSelector.ts` | Selezione intelligente dell'account con algoritmo di punteggio: considera la priorità, lo stato di salute, la posizione nel round robin e lo stato di recupero per scegliere l'account ottimale per ogni richiesta. | -| `contextManager.ts` | Gestione del ciclo di vita del contesto della richiesta: crea e tiene traccia degli oggetti di contesto per richiesta con metadati (ID della richiesta, timestamp, informazioni sul provider) per il debug e il logging. | -| `ipFilter.ts` | Controllo degli accessi basato su IP: supporta le modalità lista consentita e lista bloccata. Convalida l'IP del client rispetto alle regole configurate prima di elaborare le richieste API. | -| `sessionManager.ts` | Tracciamento delle sessioni con l'impronta digitale del client: tiene traccia delle sessioni attive utilizzando identificatori client con hash, monitora i conteggi delle richieste e fornisce metriche di sessione. | -| `signatureCache.ts` | Cache di deduplicazione basata sulla firma: impedisce le richieste duplicate memorizzando nella cache le firme delle richieste recenti e restituendo risposte memorizzate nella cache per richieste identiche entro un intervallo di tempo. | -| `systemPrompt.ts` | Iniezione di prompt di sistema globale: antepone o accoda un prompt di sistema configurabile a tutte le richieste, con gestione della compatibilità per provider. | -| `thinkingBudget.ts` | Gestione del budget dei token di ragionamento: supporta le modalità passthrough, automatica (configurazione del pensiero a strisce), personalizzata (budget fisso) e adattiva (a scala di complessità) per il controllo dei token di pensiero/ragionamento. | -| `wildcardRouter.ts` | Routing dei modelli di caratteri jolly: risolve i modelli di caratteri jolly (ad esempio, `*/claude-*`) in coppie provider/modello concrete in base alla disponibilità e alla priorità. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Deduplicazione aggiornamento token +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Macchina a stati di fallback dell'account +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Catena modello combinato +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Traduttore (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -Il **motore di traduzione dei formati** che utilizza un sistema di plugin autoregistranti. +The **format translation engine** using a self-registering plugin system. -#### Architettura +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Elenco | File | Descrizione | -| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 traduttori | Converti corpi di richiesta tra formati. Ogni file si registra automaticamente tramite `register(from, to, fn)` al momento dell'importazione. | -| `response/` | 7 traduttori | Converti blocchi di risposta in streaming tra formati. Gestisce tipi di eventi SSE, blocchi di pensiero, chiamate a strumenti. | -| `helpers/` | 6 aiutanti | Utilità condivise: `claudeHelper` (estrazione prompt di sistema, configurazione pensiero), `geminiHelper` (mappatura di parti/contenuti), `openaiHelper` (filtro formato), `toolCallHelper` (generazione ID, inserimento risposta mancante), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Motore di traduzione: `translateRequest()`, `translateResponse()`, gestione dello stato, registro. | -| `formats.ts` | — | Costanti di formato: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Progettazione chiave: plugin autoregistranti +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Utilità (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| File | Scopo | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `error.ts` | Creazione di risposte agli errori (formato compatibile con OpenAI), analisi degli errori upstream, estrazione del tempo di tentativo Antigravity dai messaggi di errore, streaming degli errori SSE. | -| `stream.ts` | **SSE Transform Stream**: la pipeline di streaming principale. Due modalità: `TRANSLATE` (traduzione del formato completo) e `PASSTHROUGH` (normalizza + estrai l'utilizzo). Gestisce il buffering dei blocchi, la stima dell'utilizzo, il monitoraggio della lunghezza del contenuto. Le istanze del codificatore/decodificatore per flusso evitano lo stato condiviso. | -| `streamHelpers.ts` | Utilità SSE di basso livello: `parseSSELine` (tollerante agli spazi bianchi), `hasValuableContent` (filtra blocchi vuoti per OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serializzazione SSE compatibile con il formato con `perf_metrics` pulizia). | -| `usageTracking.ts` | Estrazione dell'utilizzo dei token da qualsiasi formato (Claude/OpenAI/Gemini/Responses), stima con rapporti separati strumento/messaggio caratteri per token, aggiunta buffer (margine di sicurezza di 2000 token), filtraggio dei campi specifici del formato, registrazione della console con colori ANSI. | -| `requestLogger.ts` | Registrazione delle richieste basata su file (attivazione tramite `ENABLE_REQUEST_LOGS=true`). Crea cartelle di sessione con file numerati: `1_req_client.json` → `7_res_client.txt`. Tutto l'I/O è asincrono (fire-and-forget). Maschera le intestazioni riservate. | -| `bypassHandler.ts` | Intercetta modelli specifici dalla CLI di Claude (estrazione del titolo, riscaldamento, conteggio) e restituisce risposte false senza chiamare alcun fornitore. Supporta sia lo streaming che il non streaming. Intenzionalmente limitato all'ambito CLI di Claude. | -| `networkProxy.ts` | Risolve l'URL proxy in uscita per un determinato provider con precedenza: configurazione specifica del provider → configurazione globale → variabili di ambiente (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supporta le esclusioni `NO_PROXY`. Configurazione della cache per 30 secondi. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Pipeline di streaming SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Richiedi la struttura della sessione del logger +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Livello applicazione (`src/`) +### 4.7 Application Layer (`src/`) -| Elenco | Scopo | -| ------------- | ----------------------------------------------------------------------------------- | -| `src/app/` | Interfaccia utente Web, percorsi API, middleware Express, gestori di callback OAuth | -| `src/lib/` | Accesso al database (`localDb.ts`, `usageDb.ts`), autenticazione, condivisa | -| `src/mitm/` | Utilità proxy man-in-the-middle per intercettare il traffico del provider | -| `src/models/` | Definizioni del modello di database | -| `src/shared/` | Wrapper attorno alle funzioni open-sse (provider, stream, errore, ecc.) | -| `src/sse/` | Gestori endpoint SSE che collegano la libreria open-sse alle rotte Express | -| `src/store/` | Gestione dello stato dell'applicazione | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Percorsi API notevoli +#### Notable API Routes -| Itinerario | Metodi | Scopo | -| --------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | OTTIENI/INVIA/ELIMINA | CRUD per modelli personalizzati per fornitore | -| `/api/models/catalog` | OTTIENI | Catalogo aggregato di tutti i modelli (chat, incorporamento, immagine, personalizzato) raggruppati per fornitore | -| `/api/settings/proxy` | OTTIENI/INSERISCI/ELIMINA | Configurazione proxy in uscita gerarchica (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Convalida la connettività proxy e restituisce IP pubblico/latenza | -| `/v1/providers/[provider]/chat/completions` | POST | Completamenti chat dedicati per provider con convalida del modello | -| `/v1/providers/[provider]/embeddings` | POST | Incorporamenti dedicati per provider con convalida del modello | -| `/v1/providers/[provider]/images/generations` | POST | Generazione di immagini dedicate per provider con convalida del modello | -| `/api/settings/ip-filter` | OTTIENI/METTI | Gestione lista consentita/lista bloccata IP | -| `/api/settings/thinking-budget` | OTTIENI/METTI | Configurazione del budget del token di ragionamento (passthrough/auto/custom/adaptive) | -| `/api/settings/system-prompt` | OTTIENI/METTI | Iniezione rapida del sistema globale per tutte le richieste | -| `/api/sessions` | OTTIENI | Monitoraggio e metriche della sessione attiva | -| `/api/rate-limits` | OTTIENI | Stato limite tariffa per account | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Modelli di progettazione chiave +## 5. Key Design Patterns -### 5.1 Traduzione Hub-and-Spoke +### 5.1 Hub-and-Spoke Translation -Tutti i formati vengono tradotti tramite il **formato OpenAI come hub**. L'aggiunta di un nuovo provider richiede solo la scrittura di **una coppia** di traduttori (da/verso OpenAI), non N coppie. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Modello strategico dell'esecutore +### 5.2 Executor Strategy Pattern -Ogni provider dispone di una classe esecutore dedicata che eredita da `BaseExecutor`. La factory in `executors/index.ts` seleziona quella giusta in fase di runtime. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Sistema di plug-in di autoregistrazione +### 5.3 Self-Registering Plugin System -I moduli traduttore si registrano durante l'importazione tramite `register()`. Aggiungere un nuovo traduttore significa semplicemente creare un file e importarlo. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Fallback dell'account con backoff esponenziale +### 5.4 Account Fallback with Exponential Backoff -Quando un fornitore restituisce 429/401/500, il sistema può passare all'account successivo, applicando tempi di recupero esponenziali (1s → 2s → 4s → max 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Catene modello combo +### 5.5 Combo Model Chains -Una "combo" raggruppa più stringhe `provider/model`. Se il primo fallisce, passa automaticamente al successivo. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Traduzione dello streaming con stato +### 5.6 Stateful Streaming Translation -La traduzione della risposta mantiene lo stato tra i blocchi SSE (tracciamento dei blocchi di pensiero, accumulo di chiamate allo strumento, indicizzazione dei blocchi di contenuto) tramite il meccanismo `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Buffer di sicurezza per l'utilizzo +### 5.7 Usage Safety Buffer -Viene aggiunto un buffer da 2000 token all'utilizzo segnalato per impedire ai client di raggiungere i limiti della finestra di contesto a causa del sovraccarico derivante dai prompt di sistema e dalla conversione del formato. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Formati supportati +## 6. Supported Formats -| Formato | Direzione | Identificatore | -| ------------------------- | -------------------- | ------------------ | -| Completamenti OpenAI Chat | fonte + destinazione | `openai` | -| API di risposta OpenAI | fonte + destinazione | `openai-responses` | -| Claude antropico | fonte + destinazione | `claude` | -| Google Gemelli | fonte + destinazione | `gemini` | -| CLI di Google Gemini | solo obiettivo | `gemini-cli` | -| Antigravità | fonte + destinazione | `antigravity` | -| AWS Kiro | solo obiettivo | `kiro` | -| Cursore | solo obiettivo | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Provider supportati +## 7. Supported Providers -| Fornitore | Metodo di autenticazione | Esecutore testamentario | Note chiave | -| ------------------------ | ------------------------ | ----------------------- | -------------------------------------------------------- | -| Claude antropico | Chiave API o OAuth | Predefinito | Utilizza l'intestazione `x-api-key` | -| Google Gemelli | Chiave API o OAuth | Predefinito | Utilizza l'intestazione `x-goog-api-key` | -| CLI di Google Gemini | OAuth | GemelliCLI | Utilizza l'endpoint `streamGenerateContent` | -| Antigravità | OAuth | Antigravità | Fallback multi-URL, analisi dei tentativi personalizzata | -| OpenAI | Chiave API | Predefinito | Aut. alfiere | -| Codice | OAuth | Codice | Inserisce istruzioni di sistema, gestisce il pensiero | -| Copilota GitHub | OAuth + token copilota | Github | Doppio token, intestazione VSCode che imita | -| Kiro (AWS) | AWS SSO OIDC o Social | Kiro | Analisi binaria EventStream | -| Cursore IDE | Autenticazione checksum | Cursore | Codifica Protobuf, checksum SHA-256 | -| Qwen | OAuth | Predefinito | Aut. standard | -| iFlow | OAuth (base + portatore) | Predefinito | Intestazione doppia autenticazione | -| OpenRouter | Chiave API | Predefinito | Aut. alfiere | -| GLM, Kimi, MiniMax | Chiave API | Predefinito | Compatibile con Claude, usa `x-api-key` | -| `openai-compatible-*` | Chiave API | Predefinito | Dinamico: qualsiasi endpoint compatibile con OpenAI | -| `anthropic-compatible-*` | Chiave API | Predefinito | Dinamico: qualsiasi endpoint compatibile con Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Riepilogo del flusso di dati +## 8. Data Flow Summary -### Richiesta di streaming +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Richiesta di non streaming +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Bypass flusso (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/it/FEATURES.md b/docs/i18n/it/FEATURES.md index 9b0ff1ba44..82cc73b67b 100644 --- a/docs/i18n/it/FEATURES.md +++ b/docs/i18n/it/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute: Galleria delle funzionalità del dashboard +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Guida visiva a ogni sezione del dashboard OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Fornitori +## 🔌 Providers -Gestisci le connessioni dei provider AI: provider OAuth (Claude Code, Codex, Gemini CLI), provider di chiavi API (Groq, DeepSeek, OpenRouter) e provider gratuiti (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨Combo +## 🎨 Combos -Crea combinazioni di routing (model aliases, background task degradation) del modello con 6 strategie: riempimento prima, round robin, scelta potenza di due, casuale, meno utilizzata e con ottimizzazione dei costi. Ogni combo concatena più modelli con fallback automatico. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊Analitica +## 📊 Analytics -Analisi completa dell'utilizzo con consumo di token, stime dei costi, mappe di calore delle attività, grafici di distribuzione settimanale e suddivisioni per fornitore. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥Salute del sistema +## 🏥 System Health -Monitoraggio in tempo reale: tempo di attività, memoria, versione, percentili di latenza (p50/p95/p99), statistiche della cache e stati degli interruttori automatici del provider. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Parco giochi per traduttori +## 🔧 Translator Playground -Quattro modalità per il debug delle traduzioni API: **Playground** (convertitore di formato), **Chat Tester** (richieste live), **Test Bench** (test batch) e **Live Monitor** (streaming in tempo reale). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Impostazioni +## 🎮 Model Playground _(v2.0.9+)_ -Impostazioni generali, archiviazione di sistema, gestione del backup (database di esportazione/importazione), aspetto (modalità scuro/chiaro), sicurezza (include protezione endpoint API e blocco provider personalizzato), routing, resilienza e configurazione avanzata. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Strumenti CLI +## 🔧 CLI Tools -Configurazione con un clic per gli strumenti di codifica AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code e Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Richiedi registri +## 🤖 CLI Agents _(v2.0.11+)_ -Registrazione delle richieste in tempo reale con filtraggio per provider, modello, account e chiave API. Mostra i codici di stato, l'utilizzo del token, la latenza e i dettagli della risposta. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Endpoint API +## 🌐 API Endpoint -Il tuo endpoint API unificato con suddivisione delle funzionalità: completamenti chat, incorporamenti, generazione di immagini, riclassificazione, trascrizione audio e chiavi API registrate. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/it/TROUBLESHOOTING.md b/docs/i18n/it/TROUBLESHOOTING.md index 4dc59aa095..120092d63c 100644 --- a/docs/i18n/it/TROUBLESHOOTING.md +++ b/docs/i18n/it/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Risoluzione dei problemi +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Problemi comuni e soluzioni per OmniRoute. +Common problems and solutions for OmniRoute. --- -## Soluzioni rapide +## Quick Fixes -| Problema | Soluzione | -| ------------------------------------------ | ----------------------------------------------------------------------------------------------- | -| Primo accesso non funzionante | Seleziona `INITIAL_PASSWORD` in `.env` (predefinito: `123456`) | -| Il dashboard si apre sulla porta sbagliata | Imposta `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Nessun registro delle richieste in `logs/` | Imposta `ENABLE_REQUEST_LOGS=true` | -| EACCES: permesso negato | Imposta `DATA_DIR=/path/to/writable/dir` per sovrascrivere `~/.omniroute` | -| La strategia di routing non viene salvata | Aggiornamento alla v1.4.11+ (correzione dello schema Zod per la persistenza delle impostazioni) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Problemi con il fornitore +## Provider Issues -### "Il modello linguistico non ha fornito messaggi" +### "Language model did not provide messages" -**Causa:** Quota del fornitore esaurita. +**Cause:** Provider quota exhausted. -**Aggiustare:** +**Fix:** -1. Controlla il monitoraggio delle quote del dashboard -2. Utilizza una combinazione con livelli di fallback -3. Passa al livello più economico/gratuito +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Limitazione della velocità +### Rate Limiting -**Causa:** Quota di abbonamento esaurita. +**Cause:** Subscription quota exhausted. -**Aggiustare:** +**Fix:** -- Aggiungi riserva: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Utilizza GLM/MiniMax come backup economico +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Token OAuth scaduto +### OAuth Token Expired -OmniRoute aggiorna automaticamente i token. Se i problemi persistono: +OmniRoute auto-refreshes tokens. If issues persist: -1. Dashboard → Fornitore → Riconnetti -2. Elimina e aggiungi nuovamente la connessione del provider +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Problemi relativi al cloud +## Cloud Issues -### Errori di sincronizzazione cloud +### Cloud Sync Errors -1. Verifica che `BASE_URL` punti all'istanza in esecuzione (ad esempio, `http://localhost:20128`) -2. Verifica che `CLOUD_URL` punti al tuo endpoint cloud (ad esempio, `https://omniroute.dev`) -3. Mantieni i valori `NEXT_PUBLIC_*` allineati con i valori lato server +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Restituisce 500 +### Cloud `stream=false` Returns 500 -**Sintomo:** `Unexpected token 'd'...` sull'endpoint cloud per chiamate non in streaming. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Causa:** l'upstream restituisce il payload SSE mentre il client si aspetta JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Soluzione alternativa:** utilizzare `stream=true` per le chiamate dirette sul cloud. Il runtime locale include il fallback SSE→JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud dice che è connesso ma "Chiave API non valida" +### Cloud Says Connected but "Invalid API key" -1. Crea una nuova chiave dal dashboard locale (`/api/keys`) -2. Eseguire la sincronizzazione cloud: Abilita Cloud → Sincronizza ora -3. Le chiavi vecchie/non sincronizzate possono ancora restituire `401` sul cloud +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Problemi con Docker +## Docker Issues -### Lo strumento CLI risulta non installato +### CLI Tool Shows Not Installed -1. Controlla i campi di runtime: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Per la modalità portatile: utilizzare la destinazione dell'immagine `runner-cli` (CLI in bundle) -3. Per la modalità di montaggio host: impostare `CLI_EXTRA_PATHS` e montare la directory bin dell'host come di sola lettura -4. Se `installed=true` e `runnable=false`: il binario è stato trovato ma il controllo dello stato non è riuscito +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Convalida rapida del runtime +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Problemi di costi +## Cost Issues -### Costi elevati +### High Costs -1. Controlla le statistiche di utilizzo in Dashboard → Utilizzo -2. Passare dal modello principale a GLM/MiniMax -3. Utilizza il livello gratuito (Gemini CLI, iFlow) per attività non critiche -4. Imposta i budget dei costi per chiave API: Dashboard → Chiavi API → Budget +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Debug +## Debugging -### Abilita i registri delle richieste +### Enable Request Logs -Imposta `ENABLE_REQUEST_LOGS=true` nel tuo file `.env`. I registri vengono visualizzati nella directory `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Controlla lo stato del fornitore +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Archiviazione del runtime +### Runtime Storage -- Stato principale: `${DATA_DIR}/db.json` (provider, combo, alias, chiavi, impostazioni) -- Utilizzo: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Registri delle richieste: `/logs/...` (quando `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Problemi con l'interruttore automatico +## Circuit Breaker Issues -### Provider bloccato nello stato APERTO +### Provider stuck in OPEN state -Quando l'interruttore di un provider è APERTO, le richieste vengono bloccate fino alla scadenza del tempo di recupero. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Aggiustare:** +**Fix:** -1. Vai su **Dashboard → Impostazioni → Resilienza** -2. Controllare la scheda dell'interruttore del provider interessato -3. Fare clic su **Reimposta tutto** per cancellare tutti gli interruttori o attendere la scadenza del tempo di recupero -4. Verificare che il provider sia effettivamente disponibile prima di reimpostare +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Il provider continua a far scattare l'interruttore +### Provider keeps tripping the circuit breaker -Se un provider entra ripetutamente nello stato OPEN: +If a provider repeatedly enters OPEN state: -1. Selezionare **Dashboard → Salute → Salute del provider** per il modello di errore -2. Vai su **Impostazioni → Resilienza → Profili fornitore** e aumenta la soglia di errore -3. Controlla se il provider ha modificato i limiti API o richiede la riautenticazione -4. Esaminare la telemetria della latenza: un'elevata latenza può causare errori basati sul timeout +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problemi di trascrizione audio +## Audio Transcription Issues -### Errore "Modello non supportato". +### "Unsupported model" error -- Assicurati di utilizzare il prefisso corretto: `deepgram/nova-3` o `assemblyai/best` -- Verificare che il provider sia connesso in **Dashboard → Provider** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### La trascrizione restituisce un valore vuoto o non riesce +### Transcription returns empty or fails -- Controlla i formati audio supportati: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Verificare che la dimensione del file rientri nei limiti del provider (in genere < 25 MB) -- Controlla la validità della chiave API del fornitore nella scheda del fornitore +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Debug del traduttore +## Translator Debugging -Utilizza **Dashboard → Traduttore** per eseguire il debug dei problemi di traduzione del formato: +Use **Dashboard → Translator** to debug format translation issues: -| Modalità | Quando usarlo | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **Parco giochi** | Confronta i formati di input/output fianco a fianco: incolla una richiesta non riuscita per vedere come viene tradotta | -| **Tester della chat** | Invia messaggi in tempo reale e controlla l'intero payload di richiesta/risposta, comprese le intestazioni | -| **Banco di prova** | Esegui test batch su combinazioni di formati per scoprire quali traduzioni sono interrotte | -| **Monitoraggio dal vivo** | Guarda il flusso di richieste in tempo reale per individuare problemi di traduzione intermittenti | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Problemi comuni di formato +### Common format issues -- **I tag Thinking non vengono visualizzati**: controlla se il fornitore di destinazione supporta il pensiero e l'impostazione del budget per il pensiero -- **Chiamate dello strumento eliminate**: alcune traduzioni di formato potrebbero eliminare i campi non supportati; verificare in modalità Parco giochi -- **Prompt di sistema mancante** — Claude e Gemini gestiscono i prompt di sistema in modo diverso; controllare l'output della traduzione -- **L'SDK restituisce una stringa non elaborata anziché un oggetto** — Risolto nella versione 1.1.0: il sanitizer della risposta ora rimuove i campi non standard (`x_groq`, `usage_breakdown` e così via) che causano errori di convalida OpenAI SDK Pydantic -- **GLM/ERNIE rifiuta il ruolo `system`** — Risolto nella versione 1.1.0: il normalizzatore del ruolo unisce automaticamente i messaggi di sistema nei messaggi utente per modelli incompatibili -- **Ruolo `developer` non riconosciuto** — Risolto il problema nella v1.1.0: convertito automaticamente in `system` per provider non OpenAI -- **`json_schema` non funziona con Gemini** — Risolto il problema nella v1.1.0: `response_format` è ora convertito in `responseMimeType` di Gemini + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Impostazioni di resilienza +## Resilience Settings -### Il limite di velocità automatico non si attiva +### Auto rate-limit not triggering -- Il limite di velocità automatico si applica solo ai fornitori di chiavi API (non OAuth/abbonamento) -- Verificare che **Impostazioni → Resilienza → Profili fornitore** abbia il limite di velocità automatico abilitato -- Controlla se il provider restituisce codici di stato `429` o intestazioni `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Ottimizzazione del backoff esponenziale +### Tuning exponential backoff -I profili dei fornitori supportano queste impostazioni: +Provider profiles support these settings: -- **Ritardo base**: tempo di attesa iniziale dopo il primo errore (impostazione predefinita: 1 s) -- **Ritardo massimo**: limite massimo del tempo di attesa (impostazione predefinita: 30 secondi) -- **Moltiplicatore**: quanto aumentare il ritardo per guasto consecutivo (impostazione predefinita: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Mandria antituono +### Anti-thundering herd -Quando molte richieste simultanee raggiungono un provider con velocità limitata, OmniRoute utilizza mutex + limitazione automatica della velocità per serializzare le richieste e prevenire errori a catena. Questo è automatico per i fornitori di chiavi API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Sei ancora bloccato? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Problemi GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architettura**: vedi [link](ARCHITECTURE.md) per i dettagli interni -- **Riferimento API**: vedere [link](API_REFERENCE.md) per tutti gli endpoint -- **Dashboard salute**: controlla **Dashboard → Salute** per lo stato del sistema in tempo reale -- **Traduttore**: utilizza **Dashboard → Traduttore** per eseguire il debug dei problemi di formato +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/it/USER_GUIDE.md b/docs/i18n/it/USER_GUIDE.md index 2f159abb9c..5a043224df 100644 --- a/docs/i18n/it/USER_GUIDE.md +++ b/docs/i18n/it/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Guida per l'utente +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Guida completa per la configurazione dei provider, la creazione di combinazioni, l'integrazione degli strumenti CLI e la distribuzione di OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Sommario +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Guida completa per la configurazione dei provider, la creazione di combinazioni, --- -## 💰 Prezzi in breve +## 💰 Pricing at a Glance -| Livello | Fornitore | Costo | Reimpostazione quota | Ideale per | -| ------------------ | --------------------- | ----------------- | ------------------------ | ------------------------ | -| **💳 ABBONAMENTO** | Codice Claude (Pro) | $20/mese | 5 ore + settimanale | Già iscritto | -| | Codice (Plus/Pro) | $20-200/mese | 5 ore + settimanale | Utenti OpenAI | -| | Gemelli CLI | **GRATIS** | 180K/mese + 1K/giorno | Tutti! | -| | Copilota GitHub | $ 10-19/mese | Mensile | Utenti GitHub | -| **🔑 CHIAVE API** | Ricerca profonda | Paga per utilizzo | Nessuno | Ragionamento economico | -| | Groq | Paga per utilizzo | Nessuno | Inferenza ultraveloce | -| | xAI (Grok) | Paga per utilizzo | Nessuno | Grok 4 ragionamento | -| | Maestrale | Paga per utilizzo | Nessuno | Modelli ospitati nell'UE | -| | Perplessità | Paga per utilizzo | Nessuno | Ricerca aumentata | -| | Insieme AI | Paga per utilizzo | Nessuno | Modelli open source | -| | Fuochi d'artificio AI | Paga per utilizzo | Nessuno | Immagini FLUX veloci | -| | Cerebri | Paga per utilizzo | Nessuno | Velocità su scala wafer | -| | Coerenza | Paga per utilizzo | Nessuno | Comando R+ RAG | -| | NVIDIA NIM | Paga per utilizzo | Nessuno | Modelli di impresa | -| **💰 ECONOMICO** | GLM-4.7 | $ 0,6/1 milione | Tutti i giorni 10:00 | Backup del budget | -| | MiniMax M2.1 | $ 0,2/1 milione | 5 ore di rotazione | Opzione più economica | -| | Kimi K2 | $ 9/mese fisso | 10 milioni di token/mese | Costo prevedibile | -| **🆓 GRATUITO** | iFlow | $0 | Illimitato | 8 modelli gratuiti | -| | Qwen | $0 | Illimitato | 3 modelli gratuiti | -| | Kiro | $0 | Illimitato | Claude libero | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Suggerimento da professionista:** Inizia con la combinazione Gemini CLI (180.000 gratuiti al mese) + iFlow (gratuito illimitato) = costo $ 0! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Casi d'uso +## 🎯 Use Cases -### Caso 1: "Ho un abbonamento Claude Pro" +### Case 1: "I have Claude Pro subscription" -**Problema:** La quota scade inutilizzata, limiti di velocità durante la codifica pesante +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Caso 2: "Voglio zero costi" +### Case 2: "I want zero cost" -**Problema:** non posso permettermi abbonamenti, ho bisogno di una codifica IA affidabile +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Caso 3: "Ho bisogno di codifica 24 ore su 24, 7 giorni su 7, senza interruzioni" +### Case 3: "I need 24/7 coding, no interruptions" -**Problema:** Scadenze, non posso permettermi tempi di inattività +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Caso 4: "Voglio un'intelligenza artificiale GRATUITA in OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Problema:** È necessario un assistente AI nelle app di messaggistica, completamente gratuito +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Configurazione del fornitore +## 📖 Provider Setup -### 🔐 Fornitori di abbonamenti +### 🔐 Subscription Providers -#### Codice Claude (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Suggerimento professionale:** usa Opus per attività complesse, Sonnet per la velocità. OmniRoute tiene traccia della quota per modello! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### Codice OpenAI (Plus/Pro) +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (180.000 GRATIS al mese!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Miglior rapporto qualità-prezzo:** Enorme livello gratuito! Utilizzalo prima dei livelli a pagamento. +**Best Value:** Huge free tier! Use this before paid tiers. -#### Copilota GitHub +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Fornitori economici +### 💰 Cheap Providers -#### GLM-4.7 (ripristino giornaliero, $ 0,6/1 milione) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Iscriviti: [Zhipu AI](https://open.bigmodel.cn/) -2. Ottieni la chiave API dal piano di codifica -3. Dashboard → Aggiungi chiave API: Provider: `glm`, Chiave API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Utilizza:** `glm/glm-4.7` — **Suggerimento professionale:** Il piano di codifica offre una quota 3× a un costo di 1/7! Resetta ogni giorno alle 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (ripristino in 5 ore, $ 0,20/1 milione) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Iscriviti: [MiniMax](https://www.minimax.io/) -2. Ottieni chiave API → Dashboard → Aggiungi chiave API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Utilizza:** `minimax/MiniMax-M2.1` — **Suggerimento professionale:** Opzione più economica per contesti lunghi (token da 1 milione)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/mese fisso) +#### Kimi K2 ($9/month flat) -1. Iscriviti: [Moonshot AI](https://platform.moonshot.ai/) -2. Ottieni chiave API → Dashboard → Aggiungi chiave API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Utilizza:** `kimi/kimi-latest` — **Suggerimento da professionista:** $ 9/mese fissi per 10 milioni di token = $ 0,90/1 milione di costi effettivi! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 Fornitori GRATUITI +### 🆓 FREE Providers -#### iFlow (8 modelli GRATUITI) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 modelli GRATUITI) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRATIS) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨Combo +## 🎨 Combos -### Esempio 1: Massimizza l'abbonamento → Backup economico +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Esempio 2: solo gratuito (costo zero) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧Integrazione CLI +## 🔧 CLI Integration -### IDE del cursore +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Codice Claude +### Claude Code -Modifica `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Modifica `~/.claude/config.json`: } ``` -### Codice CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Modifica `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Modifica `~/.openclaw/openclaw.json`: } ``` -**Oppure utilizza Dashboard:** Strumenti CLI → OpenClaw → Configurazione automatica +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Continua / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Distribuzione +## 🚀 Deployment -### Distribuzione VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### Finestra mobile +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Per la modalità integrata nell'host con i file binari della CLI, consulta la sezione Docker nella documentazione principale. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Variabili d'ambiente +### Environment Variables -| Variabile | Predefinito | Descrizione | -| --------------------- | ------------------------------------ | -------------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Segreto firma JWT (**cambio di produzione**) | -| `INITIAL_PASSWORD` | `123456` | Prima password di accesso | -| `DATA_DIR` | `~/.omniroute` | Directory dati (db, utilizzo, log) | -| `PORT` | quadro predefinito | Porta di servizio (`20128` negli esempi) | -| `HOSTNAME` | quadro predefinito | Associa host (Docker per impostazione predefinita è `0.0.0.0`) | -| `NODE_ENV` | impostazione predefinita di runtime | Imposta `production` per la distribuzione | -| `BASE_URL` | `http://localhost:20128` | URL di base interno lato server | -| `CLOUD_URL` | `https://omniroute.dev` | URL di base dell'endpoint di sincronizzazione cloud | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Segreto HMAC per le chiavi API generate | -| `REQUIRE_API_KEY` | `false` | Applica la chiave API Bearer su `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Abilita i log di richiesta/risposta | -| `AUTH_COOKIE_SECURE` | `false` | Forza il cookie di autenticazione `Secure` (dietro il proxy inverso HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Per il riferimento completo alle variabili di ambiente, vedere [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Modelli Disponibili +## 📊 Available Models
-Visualizza tutti i modelli disponibili +View all available models -**Codice Claude (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Codice (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATUITO: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Copilota GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — $ 0,6/1 milione: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $ 0,2/1 milione: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATUITO: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATUITO: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATUITO: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -399,17 +458,17 @@ Per il riferimento completo alle variabili di ambiente, vedere [README](../READM **xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**Maestrale (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Perplessità (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Insieme AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Fuochi d'artificio AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Cerebra (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Coerenza (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Per il riferimento completo alle variabili di ambiente, vedere [README](../READM --- -## 🧩 Funzionalità avanzate +## 🧩 Advanced Features -### Modelli personalizzati +### Custom Models -Aggiungi qualsiasi ID modello a qualsiasi provider senza attendere un aggiornamento dell'app: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Oppure utilizza la Dashboard: **Provider → [Provider] → Modelli personalizzati**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Percorsi di provider dedicati +### Dedicated Provider Routes -Instrada le richieste direttamente a un fornitore specifico con convalida del modello: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Se mancante, il prefisso del provider viene aggiunto automaticamente. I modelli non corrispondenti restituiscono `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Configurazione del proxy di rete +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Precedenza:** Specifico per chiave → Specifico per combo → Specifico per provider → Globale → Ambiente. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API del catalogo modelli +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Restituisce modelli raggruppati per provider con tipi (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Sincronizzazione nel cloud +### Cloud Sync -- Sincronizza provider, combo e impostazioni su tutti i dispositivi -- Sincronizzazione automatica in background con timeout + fail-fast -- Preferisci lato server `BASE_URL`/`CLOUD_URL` in produzione +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (Fase 9) +### LLM Gateway Intelligence (Phase 9) -- **Cache semantica**: memorizza automaticamente nella cache le risposte non in streaming, temperatura=0 (ignora con `X-OmniRoute-No-Cache: true`) -- **Idempotenza richiesta**: deduplica le richieste entro 5 secondi tramite l'intestazione `Idempotency-Key` o `X-Request-Id` -- **Monitoraggio dei progressi**: attivazione degli eventi SSE `event: progress` tramite l'intestazione `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Parco giochi per traduttori +### Translator Playground -Accesso tramite **Dashboard → Traduttore**. Eseguire il debug e visualizzare il modo in cui OmniRoute traduce le richieste API tra provider. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Modalità | Scopo | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| **Parco giochi** | Seleziona i formati di origine/destinazione, incolla una richiesta e visualizza immediatamente l'output tradotto | -| **Tester della chat** | Invia messaggi di chat dal vivo tramite il proxy e controlla l'intero ciclo di richiesta/risposta | -| **Banco di prova** | Esegui test batch su più combinazioni di formati per verificare la correttezza della traduzione | -| **Monitoraggio dal vivo** | Guarda le traduzioni in tempo reale mentre le richieste passano attraverso il proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Casi d'uso:** +**Use cases:** -- Debug del motivo per cui una specifica combinazione client/provider non riesce -- Verificare che i tag pensanti, le chiamate agli strumenti e i prompt di sistema vengano tradotti correttamente -- Confronta le differenze di formato tra i formati OpenAI, Claude, Gemini e Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Strategie di instradamento +### Routing Strategies -Configura tramite **Dashboard → Impostazioni → Routing**. +Configure via **Dashboard → Settings → Routing**. -| Strategia | Descrizione | -| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| **Compila prima** | Utilizza gli account in ordine di priorità: l'account principale gestisce tutte le richieste fino a quando non è disponibile | -| **Round Robin** | Scorre tutti gli account con un limite permanente configurabile (impostazione predefinita: 3 chiamate per account) | -| **P2C (il potere di due scelte)** | Scegli 2 account casuali e percorsi verso quello più sano: bilancia il carico con la consapevolezza della salute | -| **Casuale** | Seleziona casualmente un account per ciascuna richiesta utilizzando Fisher-Yates shuffle | -| **Meno usato** | Indirizza all'account con il timestamp `lastUsedAt` più vecchio, distribuendo il traffico in modo uniforme | -| **Costi ottimizzati** | Instrada all'account con il valore di priorità più basso, ottimizzando per i fornitori a basso costo | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Alias ​​del modello con caratteri jolly +#### Wildcard Model Aliases -Crea modelli con caratteri jolly per rimappare i nomi dei modelli: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -I caratteri jolly supportano `*` (qualsiasi carattere) e `?` (carattere singolo). +Wildcards support `*` (any characters) and `?` (single character). -#### Catene di riserva +#### Fallback Chains -Definisci catene di fallback globali che si applicano a tutte le richieste: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Resilienza e interruttori automatici +### Resilience & Circuit Breakers -Configura tramite **Dashboard → Impostazioni → Resilienza**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementa la resilienza a livello di fornitore con quattro componenti: +OmniRoute implements provider-level resilience with four components: -1. **Profili fornitore**: configurazione per fornitore per: - - Soglia di guasto (quanti guasti prima dell'apertura) - - Durata del raffreddamento - - Sensibilità di rilevamento del limite di velocità - - Parametri di backoff esponenziale +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Limiti di velocità modificabili**: impostazioni predefinite a livello di sistema configurabili nel dashboard: - - **Richieste al minuto (RPM)**: numero massimo di richieste al minuto per account - - **Tempo minimo tra le richieste**: intervallo minimo in millisecondi tra le richieste - - **Numero massimo di richieste simultanee**: numero massimo di richieste simultanee per account - - Fai clic su **Modifica** per modificare, quindi su **Salva** o **Annulla**. I valori persistono tramite l'API di resilienza. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Interruttore di circuito**: tiene traccia dei guasti per fornitore e apre automaticamente il circuito quando viene raggiunta una soglia: - - **CHIUSO** (integro): le richieste fluiscono normalmente - - **APERTO**: il provider è temporaneamente bloccato dopo ripetuti errori - - **HALF_OPEN**: verifica se il provider è stato ripristinato +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Criteri e identificatori bloccati**: mostra lo stato dell'interruttore automatico e gli identificatori bloccati con funzionalità di sblocco forzato. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Rilevamento automatico del limite di velocità**: monitora le intestazioni `429` e `Retry-After` per evitare in modo proattivo di raggiungere i limiti di velocità del provider. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Suggerimento avanzato:** utilizza il pulsante **Reimposta tutto** per eliminare tutti gli interruttori automatici e i tempi di recupero quando un fornitore si riprende da un'interruzione. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Esportazione/importazione del database +### Database Export / Import -Gestisci i backup del database in **Dashboard → Impostazioni → Sistema e archiviazione**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Azione | Descrizione | -| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Esporta database** | Scarica il database SQLite corrente come file `.sqlite` | -| **Esporta tutto (.tar.gz)** | Scarica un archivio di backup completo che include: database, impostazioni, combo, connessioni al provider (nessuna credenziale), metadati della chiave API | -| **Importa database** | Carica un file `.sqlite` per sostituire il database corrente. Viene creato automaticamente un backup pre-importazione | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Convalida dell'importazione:** il file importato viene convalidato per l'integrità (controllo pragma SQLite), le tabelle richieste (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) e le dimensioni (max 100 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Casi d'uso:** +**Use Cases:** -- Migrare OmniRoute tra macchine -- Creare backup esterni per il ripristino di emergenza -- Condividi le configurazioni tra i membri del team (esporta tutto → condividi archivio) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Pannello delle impostazioni +### Settings Dashboard -La pagina delle impostazioni è organizzata in 5 schede per una facile navigazione: +The settings page is organized into 5 tabs for easy navigation: -| Scheda | Contenuto | -| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| **Sicurezza** | Impostazioni accesso/password, controllo accesso IP, autenticazione API per `/models` e blocco provider | -| **Percorso** | Strategia di routing globale (6 opzioni), alias del modello con caratteri jolly, catene di fallback, impostazioni predefinite combinate | -| **Resilienza** | Profili dei fornitori, limiti di velocità modificabili, stato dell'interruttore automatico, policy e identificatori bloccati | -| **AI** | Pensare alla configurazione del budget, all'inserimento dei prompt del sistema globale, alle statistiche della cache dei prompt | -| **Avanzato** | Configurazione proxy globale (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Gestione dei costi e del budget +### Costs & Budget Management -Accesso tramite **Dashboard → Costi**. +Access via **Dashboard → Costs**. -| Scheda | Scopo | -| ------------ | --------------------------------------------------------------------------------------------------------------- | -| **Bilancio** | Imposta limiti di spesa per chiave API con budget giornalieri/settimanali/mensili e monitoraggio in tempo reale | -| **Prezzi** | Visualizza e modifica le voci dei prezzi dei modelli: costo per token di input/output da 1.000 per fornitore | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Monitoraggio dei costi:** ogni richiesta registra l'utilizzo del token e calcola il costo utilizzando la tabella dei prezzi. Visualizza i dettagli in **Dashboard → Utilizzo** per provider, modello e chiave API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Trascrizione audio +### Audio Transcription -OmniRoute supporta la trascrizione audio tramite l'endpoint compatibile con OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Provider disponibili: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Formati audio supportati: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Strategie di bilanciamento combinate +### Combo Balancing Strategies -Configura il bilanciamento per combo in **Dashboard → Combo → Crea/Modifica → Strategia**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategia | Descrizione | -| ---------------------------- | ------------------------------------------------------------------------------------------- | -| **Round-Robin** | Ruota i modelli in sequenza | -| **Priorità** | Prova sempre il primo modello; ricorre solo in caso di errore | -| **Casuale** | Sceglie un modello casuale dalla combo per ogni richiesta | -| **Ponderato** | Percorsi proporzionali in base ai pesi assegnati per modello | -| **Meno utilizzato** | Indirizza al modello con il minor numero di richieste recenti (utilizza metriche combinate) | -| **Ottimizzazione dei costi** | Itinerari verso il modello disponibile più economico (utilizza la tabella dei prezzi) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Le impostazioni predefinite globali della combo possono essere impostate in **Dashboard → Impostazioni → Routing → Impostazioni combo**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Pannello di controllo della salute +### Health Dashboard -Accesso tramite **Dashboard → Salute**. Panoramica sullo stato del sistema in tempo reale con 6 carte: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Carta | Cosa mostra | -| ---------------------------- | ---------------------------------------------------------------------------------- | -| **Stato del sistema** | Tempo di attività, versione, utilizzo della memoria, directory dei dati | -| **Salute del fornitore** | Stato dell'interruttore automatico per provider (chiuso/aperto/semiaperto) | -| **Limiti di tariffa** | Raffreddamenti del limite di velocità attivi per account con tempo rimanente | -| **Blocchi attivi** | Provider temporaneamente bloccati dalla politica di blocco | -| **Cache delle firme** | Statistiche della cache di deduplicazione (chiavi attive, percentuale di successo) | -| **Telemetria della latenza** | Aggregazione della latenza p50/p95/p99 per provider | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Suggerimento avanzato:** la pagina Salute si aggiorna automaticamente ogni 10 secondi. Utilizza la scheda dell'interruttore per identificare quali fornitori stanno riscontrando problemi. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/ja/API_REFERENCE.md b/docs/i18n/ja/API_REFERENCE.md index 96fd9469a8..b795722c11 100644 --- a/docs/i18n/ja/API_REFERENCE.md +++ b/docs/i18n/ja/API_REFERENCE.md @@ -1,12 +1,12 @@ -# APIリファレンス +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -すべての OmniRoute API エンドポイントの完全なリファレンス。 +Complete reference for all OmniRoute API endpoints. --- -## 目次 +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## チャットの完了 +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### カスタムヘッダー +### Custom Headers -| ヘッダー | 方向 | 説明 | -| ------------------------ | ---------- | --------------------------------------------------- | ------------------------ | -| `X-OmniRoute-No-Cache` | リクエスト | キャッシュをバイパスするには、`true` に設定します。 | -| `X-OmniRoute-Progress` | リクエスト | 進行状況イベントの場合は `true` に設定します。 | -| `Idempotency-Key` | リクエスト | 重複排除キー (5 秒ウィンドウ) | -| `X-Request-Id` | リクエスト | 代替の重複排除キー | -| `X-OmniRoute-Cache` | 応答 | `HIT` または `MISS` (非ストリーミング) | -| `X-OmniRoute-Idempotent` | 応答 | `true` (重複排除の場合) | -| `X-OmniRoute-Progress` | 応答 | `enabled` | で進行状況を追跡する場合 | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## 埋め込み +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -利用可能なプロバイダー: Nebius、OpenAI、Mistral、Togetter AI、Fireworks、NVIDIA。 +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## 画像の生成 +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -利用可能なプロバイダー: OpenAI (DALL-E)、xAI (Grok Image)、Togetter AI (FLUX)、Fireworks AI。 +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## モデルのリスト +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## 互換性エンドポイント +## Compatibility Endpoints -| 方法 | パス | フォーマット | -| ---- | --------------------------- | --------------------- | -| 投稿 | `/v1/chat/completions` | オープンAI | -| 投稿 | `/v1/messages` | 人類 | -| 投稿 | `/v1/responses` | OpenAI の応答 | -| 投稿 | `/v1/embeddings` | オープンAI | -| 投稿 | `/v1/images/generations` | オープンAI | -| 入手 | `/v1/models` | オープンAI | -| 投稿 | `/v1/messages/count_tokens` | 人類 | -| 入手 | `/v1beta/models` | ジェミニ | -| 投稿 | `/v1beta/models/{...path}` | Gemini コンテンツ生成 | -| 投稿 | `/v1/api/chat` | オラマ | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### 専用プロバイダー ルート +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -プロバイダーのプレフィックスが存在しない場合は、自動的に追加されます。モデルが一致しない場合は、`400` が返されます。 +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## セマンティック キャッシュ +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -応答例: +Response example: ```json { @@ -162,154 +162,164 @@ DELETE /api/cache --- -## ダッシュボードと管理 +## Dashboard & Management -### 認証 +### Authentication -| エンドポイント | 方法 | 説明 | -| ----------------------------- | ------- | ------------------------------------ | -| `/api/auth/login` | 投稿 | ログイン | -| `/api/auth/logout` | 投稿 | ログアウト | -| `/api/settings/require-login` | GET/PUT | ログインが必要かどうかを切り替えます | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### プロバイダー管理 +### Provider Management -| エンドポイント | 方法 | 説明 | -| ---------------------------- | -------------- | ---------------------------- | -| `/api/providers` | 取得/投稿 | プロバイダーのリスト/作成 | -| `/api/providers/[id]` | 取得/挿入/削除 | プロバイダーを管理する | -| `/api/providers/[id]/test` | 投稿 | プロバイダー接続をテストする | -| `/api/providers/[id]/models` | 入手 | プロバイダーモデルのリスト | -| `/api/providers/validate` | 投稿 | プロバイダー構成を検証する | -| `/api/provider-nodes*` | いろいろ | プロバイダーノード管理 | -| `/api/provider-models` | 取得/投稿/削除 | カスタムモデル | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth フロー +### OAuth Flows -| エンドポイント | 方法 | 説明 | -| -------------------------------- | -------- | ------------------------ | -| `/api/oauth/[provider]/[action]` | いろいろ | プロバイダー固有の OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### ルーティングと構成 +### Routing & Config -| エンドポイント | 方法 | 説明 | -| --------------------- | --------- | --------------------------------------- | -| `/api/models/alias` | 取得/投稿 | モデルの別名 | -| `/api/models/catalog` | 入手 | プロバイダー + タイプ別のすべてのモデル | -| `/api/combos*` | いろいろ | コンボ管理 | -| `/api/keys*` | いろいろ | API キー管理 | -| `/api/pricing` | 入手 | モデルの価格 | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### 使用状況と分析 +### Usage & Analytics -| エンドポイント | 方法 | 説明 | -| --------------------------- | ---- | ---------------------- | -| `/api/usage/history` | 入手 | 利用履歴 | -| `/api/usage/logs` | 入手 | 使用ログ | -| `/api/usage/request-logs` | 入手 | リクエストレベルのログ | -| `/api/usage/[connectionId]` | 入手 | 接続ごとの使用量 | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### 設定 +### Settings -| エンドポイント | 方法 | 説明 | -| ------------------------------- | ------- | ------------------------------ | -| `/api/settings` | GET/PUT | 一般設定 | -| `/api/settings/proxy` | GET/PUT | ネットワークプロキシ設定 | -| `/api/settings/proxy/test` | 投稿 | プロキシ接続をテストする | -| `/api/settings/ip-filter` | GET/PUT | IP 許可リスト/ブロックリスト | -| `/api/settings/thinking-budget` | GET/PUT | トークンの予算の推論 | -| `/api/settings/system-prompt` | GET/PUT | グローバル システム プロンプト | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### モニタリング +### Monitoring -| エンドポイント | 方法 | 説明 | -| ------------------------ | --------- | ---------------------------- | -| `/api/sessions` | 入手 | アクティブなセッションの追跡 | -| `/api/rate-limits` | 入手 | アカウントごとのレート制限 | -| `/api/monitoring/health` | 入手 | 健康診断 | -| `/api/cache` | 取得/削除 | キャッシュ統計 / クリア | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### バックアップとエクスポート/インポート +### Backup & Export/Import -| エンドポイント | 方法 | 説明 | -| --------------------------- | ---- | ---------------------------------------------------------- | -| `/api/db-backups` | 入手 | 利用可能なバックアップをリストする | -| `/api/db-backups` | 置く | 手動バックアップを作成する | -| `/api/db-backups` | 投稿 | 特定のバックアップから復元する | -| `/api/db-backups/export` | 入手 | データベースを .sqlite ファイルとしてダウンロード | -| `/api/db-backups/import` | 投稿 | .sqlite ファイルをアップロードしてデータベースを置き換える | -| `/api/db-backups/exportAll` | 入手 | 完全バックアップを .tar.gz アーカイブとしてダウンロード | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### クラウド同期 +### Cloud Sync -| エンドポイント | 方法 | 説明 | -| ---------------------- | -------- | ---------------- | -| `/api/sync/cloud` | いろいろ | クラウド同期操作 | -| `/api/sync/initialize` | 投稿 | 同期を初期化する | -| `/api/cloud/*` | いろいろ | クラウド管理 | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI ツール +### CLI Tools -| エンドポイント | 方法 | 説明 | -| ---------------------------------- | ---- | ----------------------- | -| `/api/cli-tools/claude-settings` | 入手 | クロード CLI ステータス | -| `/api/cli-tools/codex-settings` | 入手 | Codex CLI ステータス | -| `/api/cli-tools/droid-settings` | 入手 | Droid CLI ステータス | -| `/api/cli-tools/openclaw-settings` | 入手 | OpenClaw CLI ステータス | -| `/api/cli-tools/runtime/[toolId]` | 入手 | 汎用 CLI ランタイム | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -CLI 応答には、`installed`、`runnable`、`command`、`commandPath`、`runtimeMode`、`reason` が含まれます。 +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### 復元力とレート制限 +### ACP Agents -| エンドポイント | 方法 | 説明 | -| ----------------------- | ------- | ------------------------------------ | -| `/api/resilience` | GET/PUT | 回復力プロファイルを取得/更新する | -| `/api/resilience/reset` | 投稿 | サーキットブレーカーをリセットする | -| `/api/rate-limits` | 入手 | アカウントごとのレート制限ステータス | -| `/api/rate-limit` | 入手 | グローバルレート制限の設定 | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### 評価 +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| エンドポイント | 方法 | 説明 | -| -------------- | --------- | --------------------------------- | -| `/api/evals` | 取得/投稿 | 評価スイートのリスト / 評価の実行 | +### Resilience & Rate Limits -### ポリシー +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| エンドポイント | 方法 | 説明 | -| --------------- | -------------- | ------------------------------- | -| `/api/policies` | 取得/投稿/削除 | ルーティング ポリシーを管理する | +### Evals -### コンプライアンス +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| エンドポイント | 方法 | 説明 | -| --------------------------- | ---- | ----------------------------------- | -| `/api/compliance/audit-log` | 入手 | コンプライアンス監査ログ (最後の N) | +### Policies -### v1beta (Gemini 互換) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| エンドポイント | 方法 | 説明 | -| -------------------------- | ---- | --------------------------------------- | -| `/v1beta/models` | 入手 | Gemini 形式でモデルをリストする | -| `/v1beta/models/{...path}` | 投稿 | Gemini `generateContent` エンドポイント | +### Compliance -これらのエンドポイントは、ネイティブの Gemini SDK 互換性を期待するクライアント向けに、Gemini の API 形式を反映しています。 +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### 内部/システム API +### v1beta (Gemini-Compatible) -| エンドポイント | 方法 | 説明 | -| --------------- | ---- | --------------------------------------------------- | -| `/api/init` | 入手 | アプリケーション初期化チェック (最初の実行時に使用) | -| `/api/tags` | 入手 | Ollama 互換モデル タグ (Ollama クライアント用) | -| `/api/restart` | 投稿 | サーバーの正常な再起動をトリガーする | -| `/api/shutdown` | 投稿 | サーバーの正常なシャットダウンをトリガーする | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **注:** これらのエンドポイントは、システムによって内部的に使用されるか、Ollama クライアントの互換性のために使用されます。通常、これらはエンド ユーザーによって呼び出されることはありません。 +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## 音声文字起こし +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Deepgram または AssemblyAI を使用して音声ファイルを文字起こしします。 +Transcribe audio files using Deepgram or AssemblyAI. -**リクエスト:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**応答:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**サポートされているプロバイダー:** `deepgram/nova-3`、`assemblyai/best`。 +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**サポートされている形式:** `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。 +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Ollama の互換性 +## Ollama Compatibility -Ollama の API 形式を使用するクライアントの場合: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -リクエストは、Ollama 形式と内部形式の間で自動的に変換されます。 +Requests are automatically translated between Ollama and internal formats. --- -## テレメトリ +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**応答:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## 予算 +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## モデルの利用可能性 +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## リクエストの処理 +## Request Processing -1. クライアントはリクエストを `/v1/*` に送信します -2. ルート ハンドラーが `handleChat`、`handleEmbedding`、`handleAudioTranscription`、または `handleImageGeneration` を呼び出します。 -3. モデルが解決されます (直接プロバイダー/モデルまたはエイリアス/コンボ) -4. アカウント可用性フィルタリングを使用してローカル DB から選択された資格情報 -5. チャットの場合: `handleChatCore` — フォーマット検出、変換、キャッシュ チェック、冪等性チェック -6. プロバイダーエグゼキューターがアップストリームリクエストを送信します -7. 応答はクライアント形式に変換されるか (チャット)、またはそのまま返されます (埋め込み/画像/音声) -8. 使用状況/ログの記録 -9. フォールバックはコンボルールに従ってエラーに適用されます +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -完全なアーキテクチャリファレンス: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## 認証 +## Authentication -- ダッシュボード ルート (`/dashboard/*`) は `auth_token` Cookie を使用します -- ログインには保存されたパスワード ハッシュが使用されます。 `INITIAL_PASSWORD` へのフォールバック -- `requireLogin` は `/api/settings/require-login` 経由で切り替え可能 -- `/v1/*` ルートでは、`REQUIRE_API_KEY=true` の場合、オプションでベアラー API キーが必要です +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/ja/ARCHITECTURE.md b/docs/i18n/ja/ARCHITECTURE.md index 60bddbb1ef..258d62df53 100644 --- a/docs/i18n/ja/ARCHITECTURE.md +++ b/docs/i18n/ja/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# オムニルート アーキテクチャ +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_最終更新日: 2026-02-18_ +_Last updated: 2026-03-04_ -## エグゼクティブサマリー +## Executive Summary -OmniRoute は、Next.js 上に構築されたローカル AI ルーティング ゲートウェイおよびダッシュボードです。 -これは、単一の OpenAI 互換エンドポイント (`/v1/*`) を提供し、変換、フォールバック、トークン更新、および使用状況追跡を使用して複数の上流プロバイダー間でトラフィックをルーティングします。 +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -コア機能: +Core capabilities: -- CLI/ツール用の OpenAI 互換 API サーフェス (28 プロバイダー) -- プロバイダ形式間でのリクエスト/レスポンスの変換 -- モデル コンボ フォールバック (マルチモデル シーケンス) -- アカウントレベルのフォールバック (プロバイダーごとにマルチアカウント) -- OAuth + APIキープロバイダ接続管理 -- `/v1/embeddings` による埋め込み生成 (6 プロバイダー、9 モデル) -- `/v1/images/generations` によるイメージ生成 (4 プロバイダー、9 モデル) -- 推論モデルのタグ解析 (`...`) を考える -- 厳密な OpenAI SDK 互換性のための応答のサニタイズ -- プロバイダー間の互換性のための役割の正規化 (開発者→システム、システム→ユーザー) -- 構造化出力変換 (json_schema → Gemini responseSchema) -- プロバイダー、キー、エイリアス、コンボ、設定、価格設定のローカル永続性 -- 使用量/コストの追跡とリクエストのロギング -- マルチデバイス/状態同期のためのオプションのクラウド同期 -- API アクセス制御用の IP 許可リスト/ブロックリスト -- 予算管理を考える (パススルー/自動/カスタム/アダプティブ) -- グローバル システム プロンプト インジェクション -- セッション追跡とフィンガープリンティング -- プロバイダー固有のプロファイルによるアカウントごとの強化されたレート制限 -- プロバイダーの回復力を高めるサーキット ブレーカー パターン -- ミューテックスロックによるアンチサンダーリング保護 -- 署名ベースのリクエスト重複排除キャッシュ -- ドメイン層: モデルの可用性、コスト ルール、フォールバック ポリシー、ロックアウト ポリシー -- ドメイン状態の永続性 (フォールバック、バジェット、ロックアウト、サーキット ブレーカー用の SQLite ライトスルー キャッシュ) -- リクエストを一元的に評価するためのポリシー エンジン (ロックアウト → 予算 → フォールバック) -- p50/p95/p99 レイテンシ集約を使用したテレメトリのリクエスト -- エンドツーエンド トレース用の相関 ID (X-Request-Id) -- API キーごとのオプトアウトによるコンプライアンス監査ログ -- LLM品質保証のための評価フレームワーク -- リアルタイムのサーキット ブレーカー ステータスを備えた Resilience UI ダッシュボード -- モジュラー OAuth プロバイダー (`src/lib/oauth/providers/` の下の 12 個の個別モジュール) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -プライマリ ランタイム モデル: +Primary runtime model: -- `src/app/api/*` の下の Next.js アプリ ルートは、ダッシュボード API と互換性 API の両方を実装します -- `src/sse/*` + `open-sse/*` の共有 SSE/ルーティング コアは、プロバイダーの実行、変換、ストリーミング、フォールバック、および使用法を処理します。 +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## 範囲と境界 +## Scope and Boundaries -### 範囲内 +### In Scope -- ローカルゲートウェイランタイム -- ダッシュボード管理 API -- プロバイダー認証とトークンの更新 -- 翻訳と SSE ストリーミングのリクエスト -- ローカル状態 + 使用状況の永続性 -- オプションのクラウド同期オーケストレーション +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### 範囲外 +### Out of Scope -- `NEXT_PUBLIC_CLOUD_URL` の背後にあるクラウド サービスの実装 -- ローカル プロセス外のプロバイダー SLA/コントロール プレーン -- 外部 CLI バイナリ自体 (Claude CLI、Codex CLI など) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## 高レベルのシステムコンテキスト +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## コア ランタイム コンポーネント +## Core Runtime Components -## 1) API とルーティング レイヤー (Next.js アプリ ルート) +## 1) API and Routing Layer (Next.js App Routes) -メインディレクトリ: +Main directories: -- `src/app/api/v1/*` および `src/app/api/v1beta/*` (互換性 API) -- `src/app/api/*` 管理/構成 API 用 -- 次に、`next.config.mjs` で書き換えて、`/v1/*` を `/api/v1/*` にマップします。 +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -重要な互換性ルート: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — `custom: true` のカスタム モデルが含まれます -- `src/app/api/v1/embeddings/route.ts` — 埋め込み生成 (6 プロバイダー) -- `src/app/api/v1/images/generations/route.ts` — 画像生成 (Antigravity/Nebius を含む 4 つ以上のプロバイダー) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — プロバイダーごとの専用チャット -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — プロバイダーごとの専用埋め込み -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — プロバイダーごとの専用イメージ +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -管理ドメイン: +Management domains: -- 認証/設定: `src/app/api/auth/*`、`src/app/api/settings/*` -- プロバイダー/接続: `src/app/api/providers*` -- プロバイダーノード: `src/app/api/provider-nodes*` -- カスタム モデル: `src/app/api/provider-models` (GET/POST/DELETE) -- モデルカタログ: `src/app/api/models/catalog` (GET) -- プロキシ構成: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- キー/エイリアス/コンボ/価格: `src/app/api/keys*`、`src/app/api/models/alias`、`src/app/api/combos*`、`src/app/api/pricing` -- 使用法: `src/app/api/usage/*` -- 同期/クラウド: `src/app/api/sync/*`、`src/app/api/cloud/*` -- CLI ツールヘルパー: `src/app/api/cli-tools/*` -- IP フィルター: `src/app/api/settings/ip-filter` (GET/PUT) -- 検討予算: `src/app/api/settings/thinking-budget` (GET/PUT) -- システム プロンプト: `src/app/api/settings/system-prompt` (GET/PUT) -- セッション: `src/app/api/sessions` (GET) -- レート制限: `src/app/api/rate-limits` (GET) -- 復元力: `src/app/api/resilience` (GET/PATCH) — プロバイダー プロファイル、サーキット ブレーカー、レート制限状態 -- レジリエンスのリセット: `src/app/api/resilience/reset` (POST) — ブレーカー + クールダウンをリセット -- キャッシュ統計: `src/app/api/cache/stats` (GET/DELETE) -- 利用可能なモデル: `src/app/api/models/availability` (GET/POST) -- テレメトリ: `src/app/api/telemetry/summary` (GET) -- 予算: `src/app/api/usage/budget` (GET/POST) -- フォールバック チェーン: `src/app/api/fallback/chains` (GET/POST/DELETE) -- コンプライアンス監査: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST)、`src/app/api/evals/[suiteId]` (GET) -- ポリシー: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + 翻訳コア +## 2) SSE + Translation Core -メインフローモジュール: +Main flow modules: -- エントリ: `src/sse/handlers/chat.ts` -- コアオーケストレーション: `open-sse/handlers/chatCore.ts` -- プロバイダー実行アダプター: `open-sse/executors/*` -- フォーマット検出/プロバイダー構成: `open-sse/services/provider.ts` -- モデル解析/解決: `src/sse/services/model.ts`、`open-sse/services/model.ts` -- アカウントのフォールバック ロジック: `open-sse/services/accountFallback.ts` -- 翻訳レジストリ: `open-sse/translator/index.ts` -- ストリーム変換: `open-sse/utils/stream.ts`、`open-sse/utils/streamHandler.ts` -- 使用量の抽出/正規化: `open-sse/utils/usageTracking.ts` -- シンクタグパーサー: `open-sse/utils/thinkTagParser.ts` -- 埋め込みハンドラー: `open-sse/handlers/embeddings.ts` -- 埋め込みプロバイダー レジストリ: `open-sse/config/embeddingRegistry.ts` -- 画像生成ハンドラー: `open-sse/handlers/imageGeneration.ts` -- イメージプロバイダーレジストリ: `open-sse/config/imageRegistry.ts` -- 応答のサニタイズ: `open-sse/handlers/responseSanitizer.ts` -- ロールの正規化: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -サービス (ビジネス ロジック): +Services (business logic): -- アカウントの選択/スコアリング: `open-sse/services/accountSelector.ts` -- コンテキストのライフサイクル管理: `open-sse/services/contextManager.ts` -- IP フィルターの適用: `open-sse/services/ipFilter.ts` -- セッション追跡: `open-sse/services/sessionManager.ts` -- 重複排除のリクエスト: `open-sse/services/signatureCache.ts` -- システムプロンプトインジェクション: `open-sse/services/systemPrompt.ts` -- 予算管理を考える: `open-sse/services/thinkingBudget.ts` -- ワイルドカード モデル ルーティング: `open-sse/services/wildcardRouter.ts` -- レート制限管理: `open-sse/services/rateLimitManager.ts` -- サーキットブレーカー: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -ドメイン層モジュール: +Domain layer modules: -- 利用可能なモデル: `src/lib/domain/modelAvailability.ts` -- コストルール/予算: `src/lib/domain/costRules.ts` -- フォールバック ポリシー: `src/lib/domain/fallbackPolicy.ts` -- コンボリゾルバー: `src/lib/domain/comboResolver.ts` -- ロックアウト ポリシー: `src/lib/domain/lockoutPolicy.ts` -- ポリシー エンジン: `src/domain/policyEngine.ts` — 集中ロックアウト → 予算 → フォールバック評価 -- エラーコードカタログ: `src/lib/domain/errorCodes.ts` -- リクエストID: `src/lib/domain/requestId.ts` -- フェッチタイムアウト: `src/lib/domain/fetchTimeout.ts` -- テレメトリのリクエスト: `src/lib/domain/requestTelemetry.ts` -- コンプライアンス/監査: `src/lib/domain/compliance/index.ts` -- 評価ランナー: `src/lib/domain/evalRunner.ts` -- ドメイン状態の永続性: `src/lib/db/domainState.ts` — フォールバック チェーン、予算、コスト履歴、ロックアウト状態、サーキット ブレーカー用の SQLite CRUD +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth プロバイダー モジュール (`src/lib/oauth/providers/` の下の 12 個の個別ファイル): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- レジストリ インデックス: `src/lib/oauth/providers/index.ts` -- 個別プロバイダー: `claude.ts`、`codex.ts`、`gemini.ts`、`antigravity.ts`、`iflow.ts`、`qwen.ts`、`kimi-coding.ts`、`github.ts`、 `kiro.ts`、`cursor.ts`、`kilocode.ts`、`cline.ts` -- 薄いラッパー: `src/lib/oauth/providers.ts` — 個々のモジュールからの再エクスポート +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) 永続層 +## 3) Persistence Layer -プライマリ状態 DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- ファイル: `${DATA_DIR}/db.json` (設定されている場合は `$XDG_CONFIG_HOME/omniroute/db.json`、それ以外の場合は `~/.omniroute/db.json`) -- エンティティ: ProviderConnections、providerNodes、modelAliases、コンボ、apiKeys、設定、価格設定、**customModels**、**proxyConfig**、**ipFilter**、** ThinkingBudget**、**systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -使用状況DB: +Usage persistence: -- `src/lib/usageDb.ts` -- ファイル: `${DATA_DIR}/usage.json`、`${DATA_DIR}/log.txt`、`${DATA_DIR}/call_logs/` -- `localDb` と同じベース ディレクトリ ポリシーに従います (`DATA_DIR`、設定されている場合は `XDG_CONFIG_HOME/omniroute`) -- 重点的なサブモジュールに分解: `migrations.ts`、`usageHistory.ts`、`costCalculator.ts`、`usageStats.ts`、`callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -ドメイン状態 DB (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — ドメイン状態の CRUD 操作 -- テーブル (`src/lib/db/core.ts` で作成): `domain_fallback_chains`、`domain_budgets`、`domain_cost_history`、`domain_lockout_state`、`domain_circuit_breakers` -- ライトスルー キャッシュ パターン: メモリ内マップは実行時に権限を持ちます。変更は SQLite に同期的に書き込まれます。状態はコールド スタート時に DB から復元されます +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) 認証 + セキュリティ サーフェス +## 4) Auth + Security Surfaces -- ダッシュボード Cookie 認証: `src/proxy.ts`、`src/app/api/auth/login/route.ts` -- API キーの生成/検証: `src/shared/utils/apiKey.ts` -- プロバイダーのシークレットは `providerConnections` エントリに保持されます -- `open-sse/utils/proxyFetch.ts` (環境変数) および `open-sse/utils/networkProxy.ts` (プロバイダーごとまたはグローバルに構成可能) による送信プロキシのサポート +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) クラウド同期 +## 5) Cloud Sync -- スケジューラの初期化: `src/lib/initCloudSync.ts`、`src/shared/services/initializeCloudSync.ts` -- 定期タスク: `src/shared/services/cloudSyncScheduler.ts` -- 制御ルート: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## リクエストのライフサイクル (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## コンボ + アカウントのフォールバック フロー +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -フォールバックの決定は、ステータス コードとエラー メッセージのヒューリスティックを使用して、`open-sse/services/accountFallback.ts` によって行われます。 +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth オンボーディングとトークン更新のライフサイクル +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -ライブ トラフィック中の更新は、エグゼキュータ `refreshCredentials()` を介して `open-sse/handlers/chatCore.ts` 内で実行されます。 +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## クラウド同期ライフサイクル (有効化/同期/無効化) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -クラウドが有効な場合、定期的な同期は `CloudSyncScheduler` によってトリガーされます。 +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## データモデルとストレージマップ +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -物理ストレージ ファイル: +Physical storage files: -- メイン状態: `${DATA_DIR}/db.json` (設定されている場合は `$XDG_CONFIG_HOME/omniroute/db.json`、それ以外の場合は `~/.omniroute/db.json`) -- 使用状況統計: `${DATA_DIR}/usage.json` -- リクエストログ行: `${DATA_DIR}/log.txt` -- オプションのトランスレータ/リクエスト デバッグ セッション: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## デプロイメントトポロジ +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## モジュール マッピング (意思決定が重要) +## Module Mapping (Decision-Critical) -### ルートと API モジュール +### Route and API Modules -- `src/app/api/v1/*`、`src/app/api/v1beta/*`: 互換性 API -- `src/app/api/v1/providers/[provider]/*`: プロバイダーごとの専用ルート (チャット、埋め込み、画像) -- `src/app/api/providers*`: プロバイダー CRUD、検証、テスト -- `src/app/api/provider-nodes*`: カスタム互換ノード管理 -- `src/app/api/provider-models`: カスタム モデル管理 (CRUD) -- `src/app/api/models/catalog`: 完全なモデル カタログ API (プロバイダーごとにグループ化されたすべてのタイプ) -- `src/app/api/oauth/*`: OAuth/デバイスコードフロー -- `src/app/api/keys*`: ローカル API キーのライフサイクル -- `src/app/api/models/alias`: エイリアス管理 -- `src/app/api/combos*`: フォールバック コンボ管理 -- `src/app/api/pricing`: コスト計算のための価格設定の上書き -- `src/app/api/settings/proxy`: プロキシ構成 (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: 送信プロキシ接続テスト (POST) -- `src/app/api/usage/*`: 使用状況とログ API -- `src/app/api/sync/*` + `src/app/api/cloud/*`: クラウド同期およびクラウド対応ヘルパー -- `src/app/api/cli-tools/*`: ローカル CLI 構成ライター/チェッカー -- `src/app/api/settings/ip-filter`: IP 許可リスト/ブロックリスト (GET/PUT) -- `src/app/api/settings/thinking-budget`: 思考トークン予算構成 (GET/PUT) -- `src/app/api/settings/system-prompt`: グローバル システム プロンプト (GET/PUT) -- `src/app/api/sessions`: アクティブなセッションのリスト (GET) -- `src/app/api/rate-limits`: アカウントごとのレート制限ステータス (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### ルーティングおよび実行コア +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: リクエスト解析、コンボ処理、アカウント選択ループ -- `open-sse/handlers/chatCore.ts`: 変換、実行プログラムのディスパッチ、再試行/リフレッシュ処理、ストリームのセットアップ -- `open-sse/executors/*`: プロバイダー固有のネットワークと形式の動作 +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### 翻訳レジストリとフォーマットコンバータ +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: トランスレータ レジストリとオーケストレーション -- 翻訳者のリクエスト: `open-sse/translator/request/*` -- 応答翻訳者: `open-sse/translator/response/*` -- フォーマット定数: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### 永続性 +### Persistence -- `src/lib/localDb.ts`: 永続的な構成/状態 -- `src/lib/usageDb.ts`: 使用履歴とローリングリクエストログ +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Provider Executor カバレッジ (戦略パターン) +## Provider Executor Coverage (Strategy Pattern) -各プロバイダーには、`BaseExecutor` (`open-sse/executors/base.ts` 内) を拡張する特殊なエグゼキューターがあり、URL の構築、ヘッダーの構築、指数バックオフによる再試行、資格情報の更新フック、および `execute()` オーケストレーション メソッドを提供します。 +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| 執行者 | プロバイダー | 特殊な取り扱い | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI、Claude、Gemini、Qwen、iFlow、OpenRouter、GLM、Kimi、MiniMax、DeepSeek、Groq、xAI、Mistral、Perplexity、Togetter、Fireworks、Cerebros、Cohere、NVIDIA | プロバイダーごとの動的 URL/ヘッダー構成 | -| `AntigravityExecutor` | Google 反重力 | カスタム プロジェクト/セッション ID、解析後の再試行 | -| `CodexExecutor` | OpenAI コーデックス | システム命令を挿入し、推論努力を強制する | -| `CursorExecutor` | カーソルIDE | ConnectRPC プロトコル、Protobuf エンコーディング、チェックサムによる要求署名 | -| `GithubExecutor` | GitHub コパイロット | コパイロット トークンの更新、VSCode を模倣したヘッダー | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream バイナリ形式 → SSE 変換 | -| `GeminiCLIExecutor` | ジェミニ CLI | Google OAuth トークンの更新サイクル | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -他のすべてのプロバイダー (カスタム互換ノードを含む) は `DefaultExecutor` を使用します。 +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## プロバイダー互換性マトリックス +## Provider Compatibility Matrix -| プロバイダー | フォーマット | 認証 | ストリーム | 非ストリーム | トークンのリフレッシュ | 使用法 API | -| --------------------- | ------------------ | ----------------------------- | ----------------------- | ------------ | ---------------------- | ----------------------------- | -| クロード | クロード | APIキー/OAuth | ✅ | ✅ | ✅ | ⚠️管理者のみ | -| ジェミニ | ジェミニ | APIキー/OAuth | ✅ | ✅ | ✅ | ⚠️クラウドコンソール | -| ジェミニ CLI | ジェミニクリ | OAuth | ✅ | ✅ | ✅ | ⚠️クラウドコンソール | -| 反重力 | 反重力 | OAuth | ✅ | ✅ | ✅ | ✅ フルクォータ API | -| オープンAI | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| コーデックス | オープンナイの応答 | OAuth | ✅強制 | ❌ | ✅ | ✅ レート制限 | -| GitHub コパイロット | オープンナイ | OAuth + コパイロット トークン | ✅ | ✅ | ✅ | ✅ クォータのスナップショット | -| カーソル | カーソル | カスタムチェックサム | ✅ | ✅ | ❌ | ❌ | -| キロ | キロ | AWS SSO OIDC | ✅ (イベントストリーム) | ❌ | ✅ | ✅ 使用制限 | -| クウェン | オープンナイ | OAuth | ✅ | ✅ | ✅ | ⚠️リクエストに応じて | -| iFlow | オープンナイ | OAuth (基本) | ✅ | ✅ | ✅ | ⚠️リクエストに応じて | -| オープンルーター | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| GLM/キミ/ミニマックス | クロード | APIキー | ✅ | ✅ | ❌ | ❌ | -| ディープシーク | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| グロク | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| xAI (グロック) | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| ミストラル | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| 困惑 | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| 一緒にAI | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| 花火AI | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| 大脳 | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| コヒア | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## フォーマット翻訳の範囲 +## Format Translation Coverage -検出されたソース形式は次のとおりです。 +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -対象となる形式は次のとおりです。 +Target formats include: -- OpenAI チャット/応答 -- クロード -- ジェミニ/ジェミニ-CLI/反重力エンベロープ -- キロ -- カーソル +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -翻訳では **OpenAI をハブ形式**として使用します。すべての変換は中間として OpenAI を経由します。 +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -翻訳は、ソース ペイロードの形状とプロバイダーのターゲット形式に基づいて動的に選択されます。 +Translations are selected dynamically based on source payload shape and provider target format. -翻訳パイプラインの追加の処理レイヤー: +Additional processing layers in the translation pipeline: -- **レスポンスのサニタイズ** — OpenAI 形式のレスポンス (ストリーミングと非ストリーミングの両方) から非標準フィールドを削除し、厳密な SDK コンプライアンスを確保します。 -- **ロールの正規化** — 非 OpenAI ターゲットの場合は `developer` → `system` を変換します。システムロールを拒否するモデル (GLM、ERNIE) の `system` → `user` をマージします。 -- **思考タグ抽出** — コンテンツから `...` ブロックを解析して `reasoning_content` フィールドに変換します -- **構造化出力** — OpenAI `response_format.json_schema` を Gemini の `responseMimeType` + `responseSchema` に変換します +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## サポートされる API エンドポイント +## Supported API Endpoints -| エンドポイント | フォーマット | ハンドラー | -| -------------------------------------------------- | --------------------- | --------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAIチャット | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | クロードのメッセージ | 同じハンドラー (自動検出) | -| `POST /v1/responses` | OpenAI の応答 | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI 埋め込み | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | モデル一覧 | APIルート | -| `POST /v1/images/generations` | OpenAI 画像 | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | モデル一覧 | APIルート | -| `POST /v1/providers/{provider}/chat/completions` | OpenAIチャット | モデル検証を備えた専用のプロバイダーごと | -| `POST /v1/providers/{provider}/embeddings` | OpenAI 埋め込み | モデル検証を備えた専用のプロバイダーごと | -| `POST /v1/providers/{provider}/images/generations` | OpenAI 画像 | モデル検証を備えた専用のプロバイダーごと | -| `POST /v1/messages/count_tokens` | クロードトークン数 | APIルート | -| `GET /v1/models` | OpenAI モデルのリスト | API ルート (チャット + 埋め込み + 画像 + カスタム モデル) | -| `GET /api/models/catalog` | カタログ | プロバイダー + タイプごとにグループ化されたすべてのモデル | -| `POST /v1beta/models/*:streamGenerateContent` | 双子座出身 | APIルート | -| `GET/PUT/DELETE /api/settings/proxy` | プロキシ構成 | ネットワークプロキシ構成 | -| `POST /api/settings/proxy/test` | プロキシ接続 | プロキシの健全性/接続テスト エンドポイント | -| `GET/POST/DELETE /api/provider-models` | カスタムモデル | プロバイダーごとのカスタム モデル管理 | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## バイパスハンドラー +## Bypass Handler -バイパス ハンドラー (`open-sse/utils/bypassHandler.ts`) は、Claude CLI からの既知の「使い捨て」リクエスト (ウォームアップ ping、タイトル抽出、トークン カウント) をインターセプトし、アップストリーム プロバイダー トークンを消費せずに **偽の応答** を返します。これは、`User-Agent` に `claude-cli` が含まれている場合にのみトリガーされます。 +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## リクエストロガーパイプライン +## Request Logger Pipeline -リクエスト ロガー (`open-sse/utils/requestLogger.ts`) は、7 段階のデバッグ ロギング パイプラインを提供します。デフォルトでは無効になっており、`ENABLE_REQUEST_LOGS=true` によって有効になります。 +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -ファイルはリクエスト セッションごとに `/logs//` に書き込まれます。 +Files are written to `/logs//` for each request session. -## 障害モードと回復力 +## Failure Modes and Resilience -## 1) アカウント/プロバイダーの可用性 +## 1) Account/Provider Availability -- 一時的/レート/認証エラー時のプロバイダー アカウントのクールダウン -- リクエストが失敗する前のアカウントのフォールバック -- 現在のモデル/プロバイダー パスが枯渇した場合のコンボ モデル フォールバック +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) トークンの有効期限 +## 2) Token Expiry -- 更新可能なプロバイダーの事前チェックと再試行による更新 -- コア パスでの更新試行後の 401/403 再試行 +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) ストリームの安全性 +## 3) Stream Safety -- 切断対応ストリーム コントローラー -- ストリーム終了フラッシュと `[DONE]` 処理を備えた変換ストリーム -- プロバイダーの使用量メタデータが欠落している場合の使用量推定フォールバック +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) クラウド同期の低下 +## 4) Cloud Sync Degradation -- 同期エラーが表面化しましたが、ローカル ランタイムは継続します -- スケジューラには再試行可能なロジックがありますが、定期的な実行では現在、デフォルトで単一試行同期が呼び出されます。 +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) データの整合性 +## 5) Data Integrity -- DB 形状の移行/欠落キーの修復 -- localDb と useDb に対する破損した JSON リセットの保護策 +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## 可観測性と動作信号 +## Observability and Operational Signals -実行時の可視性ソース: +Runtime visibility sources: -- `src/sse/utils/logger.ts` からのコンソール ログ -- `usage.json` でのリクエストごとの使用量の集計 -- `log.txt` のテキスト形式のリクエスト ステータス ログ -- `ENABLE_REQUEST_LOGS=true` の場合、`logs/` の下のオプションの詳細なリクエスト/変換ログ -- UI 消費のためのダッシュボード使用エンドポイント (`/api/usage/*`) +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## セキュリティに注意が必要な境界 +## Security-Sensitive Boundaries -- JWT シークレット (`JWT_SECRET`) により、ダッシュボード セッションの Cookie 検証/署名が保護されます -- 初期パスワード フォールバック (`INITIAL_PASSWORD`、デフォルト `123456`) は実際のデプロイメントではオーバーライドする必要があります -- API キー HMAC シークレット (`API_KEY_SECRET`) は、生成されたローカル API キー形式を保護します -- プロバイダーのシークレット (API キー/トークン) はローカル DB に保存され、ファイルシステム レベルで保護される必要があります。 -- クラウド同期エンドポイントは、API キー認証 + マシン ID セマンティクスに依存します。 +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## 環境とランタイムのマトリックス +## Environment and Runtime Matrix -コードによってアクティブに使用される環境変数: +Environment variables actively used by code: -- アプリ/認証: `JWT_SECRET`、`INITIAL_PASSWORD` -- ストレージ: `DATA_DIR` -- 互換性のあるノードの動作: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- オプションのストレージ ベース オーバーライド (Linux/macOS `DATA_DIR` が設定されていない場合): `XDG_CONFIG_HOME` -- セキュリティハッシュ: `API_KEY_SECRET`、`MACHINE_ID_SALT` -- ロギング: `ENABLE_REQUEST_LOGS` -- 同期/クラウド URL: `NEXT_PUBLIC_BASE_URL`、`NEXT_PUBLIC_CLOUD_URL` -- 送信プロキシ: `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY` および小文字のバリアント -- SOCKS5 機能フラグ: `ENABLE_SOCKS5_PROXY`、`NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- プラットフォーム/ランタイム ヘルパー (アプリ固有の構成ではない): `APPDATA`、`NODE_ENV`、`PORT`、`HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## 既知のアーキテクチャに関するメモ +## Known Architectural Notes -1. `usageDb` と `localDb` は、レガシー ファイル移行と同じベース ディレクトリ ポリシー (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) を共有するようになりました。 -2. `/api/v1/route.ts` は静的モデル リストを返しますが、`/v1/models` によって使用されるメイン モデル ソースではありません。 -3. リクエスト ロガーは有効な場合、完全なヘッダー/本文を書き込みます。ログ ディレクトリを機密として扱います。 -4. クラウドの動作は、正しい `NEXT_PUBLIC_BASE_URL` とクラウド エンドポイントの到達可能性に依存します。 -5. `open-sse/` ディレクトリは、`@omniroute/open-sse` **npm ワークスペース パッケージ**として公開されます。ソース コードは `@omniroute/open-sse/...` 経由でインポートします (Next.js `transpilePackages` によって解決されます)。このドキュメントのファイル パスでは、一貫性を保つために引き続きディレクトリ名 `open-sse/` が使用されています。 -6. ダッシュボードのグラフでは、**Recharts** (SVG ベース) を使用して、アクセスしやすく対話型の分析を視覚化します (モデル使用状況の棒グラフ、成功率を示すプロバイダーの内訳表)。 -7. E2E テストは **Playwright** (`tests/e2e/`) を使用し、`npm run test:e2e` 経由で実行します。単体テストは **Node.js テスト ランナー** (`tests/unit/`) を使用し、`npm run test:plan3` 経由で実行されます。 `src/` のソース コードは **TypeScript** (`.ts`/`.tsx`) です。 `open-sse/` ワークスペースは JavaScript (`.js`) のままです。 -8. 設定ページは 5 つのタブで構成されています: セキュリティ、ルーティング (6 つのグローバル戦略: フィルファースト、ラウンドロビン、p2c、ランダム、最小使用、コスト最適化)、復元力 (編集可能なレート制限、サーキット ブレーカー、ポリシー)、AI (思考予算、システム プロンプト、プロンプト キャッシュ)、詳細 (プロキシ)。 +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## 動作検証チェックリスト +## Operational Verification Checklist -- ソースからビルド: `npm run build` -- Docker イメージのビルド: `docker build -t omniroute .` -- サービスを開始して以下を確認します。 +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- `PORT=20128` の場合、CLI ターゲット ベース URL は `http://:20128/v1` である必要があります。 +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ja/CODEBASE_DOCUMENTATION.md b/docs/i18n/ja/CODEBASE_DOCUMENTATION.md index 68557a14d0..303880c198 100644 --- a/docs/i18n/ja/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/ja/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +# omniroute — Codebase Documentation -#omniroute — コードベースのドキュメント +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> **omniroute** マルチプロバイダー AI プロキシ ルーターに関する初心者向けの包括的なガイド。 +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. オムニルートとは何ですか? +## 1. What Is omniroute? -オムニルートは、AI クライアント (Claude CLI、Codex、Cursor IDE など) と AI プロバイダー (Anthropic、Google、OpenAI、AWS、GitHub など) の間に位置する **プロキシ ルーター** です。これにより、1 つの大きな問題が解決されます。 +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **異なる AI クライアントは異なる「言語」(API 形式) を話し、異なる AI プロバイダーも異なる「言語」を期待します。** オムニルートはそれらの間で自動的に翻訳します。 +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -これを国連の万能翻訳者のようなものだと考えてください。どの代表者もあらゆる言語を話すことができ、翻訳者は他の代表者のためにそれを変換します。 +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. アーキテクチャの概要 +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### 基本原則: ハブアンドスポーク変換 +### Core Principle: Hub-and-Spoke Translation -すべての形式変換は、**OpenAI 形式をハブとして** 通過します。 +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -これは、**N²** (ペアごと) ではなく、**N トランスレーター** (フォーマットごとに 1 人) だけが必要であることを意味します。 +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. プロジェクトの構造 +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. モジュールごとの内訳 +## 4. Module-by-Module Breakdown -### 4.1 構成 (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -すべてのプロバイダー構成に関する **唯一の信頼できる情報源**。 +The **single source of truth** for all provider configuration. -| ファイル | 目的 | -| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` オブジェクトには、ベース URL、OAuth 資格情報 (デフォルト)、ヘッダー、および各プロバイダーのデフォルトのシステム プロンプトが含​​まれます。 `HTTP_STATUS`、`ERROR_TYPES`、`COOLDOWN_MS`、`BACKOFF_CONFIG`、および `SKIP_PATTERNS` も定義します。 | -| `credentialLoader.ts` | `data/provider-credentials.json` から外部資格情報をロードし、`PROVIDERS` のハードコードされたデフォルトにそれらをマージします。下位互換性を維持しながら、秘密をソース管理から除外します。 | -| `providerModels.ts` | 中央モデル レジストリ: プロバイダーのエイリアス → モデル ID をマップします。 `getModels()`、`getProviderByAlias()` のような関数。 | -| `codexInstructions.ts` | Codex リクエストに挿入されるシステム命令 (編集制約、サンドボックス ルール、承認ポリシー)。 | -| `defaultThinkingSignature.ts` | Claude モデルと Gemini モデルのデフォルトの「思考」シグネチャ。 | -| `ollamaModels.ts` | ローカル Ollama モデルのスキーマ定義 (名前、サイズ、ファミリー、量子化)。 | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### 認証情報の読み込みフロー +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 実行者 (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -エグゼキュータは、**戦略パターン**を使用して**プロバイダ固有のロジック**をカプセル化します。各エグゼキュータは、必要に応じて基本メソッドをオーバーライドします。 +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| 執行者 | プロバイダー | 主な専門分野 | -| ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | 抽象ベース: URL 構築、ヘッダー、再試行ロジック、資格情報の更新 | -| `default.ts` | クロード、ジェミニ、OpenAI、GLM、キミ、MiniMax | 標準プロバイダーの汎用 OAuth トークンの更新 | -| `antigravity.ts` | Googleクラウドコード | プロジェクト/セッション ID の生成、マルチ URL フォールバック、エラー メッセージからのカスタム再試行解析 (「2 時間 7 分 23 秒後にリセット」) | -| `cursor.ts` | カーソルIDE | **最も複雑**: SHA-256 チェックサム認証、Protobuf リクエスト エンコード、バイナリ EventStream → SSE レスポンス解析 | -| `codex.ts` | OpenAI コーデックス | システム命令の挿入、思考レベルの管理、サポートされていないパラメータの削除 | -| `gemini-cli.ts` | Google Gemini CLI | カスタム URL の構築 (`streamGenerateContent`)、Google OAuth トークンの更新 | -| `github.ts` | GitHub コパイロット | デュアル トークン システム (GitHub OAuth + Copilot トークン)、VSCode ヘッダーの模倣 | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream バイナリ解析、AMZN イベント フレーム、トークン推定 | -| `index.ts` | — | ファクトリ: デフォルトのフォールバックを使用して、プロバイダー名 → エグゼキューター クラスをマップします。 | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 ハンドラー (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**オーケストレーション レイヤー** — 変換、実行、ストリーミング、エラー処理を調整します。 +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| ファイル | 目的 | -| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **中央オーケストレーター** (約 600 行)。リクエストのライフサイクル全体を処理します: フォーマット検出→変換→エグゼキュータディスパッチ→ストリーミング/非ストリーミング応答→トークン更新→エラー処理→使用状況ログ。 | -| `responsesHandler.ts` | OpenAI の応答 API 用アダプター: 応答形式を変換 → チャット完了 → `chatCore` に送信 → SSE を応答形式に変換します。 | -| `embeddings.ts` | 埋め込み生成ハンドラー: 埋め込みモデル→プロバイダーを解決し、プロバイダー API にディスパッチし、OpenAI 互換の埋め込み応答を返します。 6 つ以上のプロバイダーをサポートします。 | -| `imageGeneration.ts` | イメージ生成ハンドラー: イメージ モデル → プロバイダーを解決し、OpenAI 互換、Gemini イメージ (Antigravity)、およびフォールバック (Nebius) モードをサポートします。 Base64 または URL イメージを返します。 | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### リクエストのライフサイクル (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 サービス (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -ハンドラーとエグゼキューターをサポートするビジネス ロジック。 +Business logic that supports the handlers and executors. -| ファイル | 目的 | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **形式検出** (`detectFormat`): リクエスト本文の構造を分析して、Claude/OpenAI/Gemini/Antigravity/Responses 形式を識別します (Claude の `max_tokens` ヒューリスティックを含む)。また、URL の構築、ヘッダーの構築、思考構成の正規化も行います。 `openai-compatible-*` および `anthropic-compatible-*` 動的プロバイダーをサポートします。 | -| `model.ts` | モデル文字列解析 (`claude/model-name` → `{provider: "claude", model: "model-name"}`)、衝突検出によるエイリアス解決、入力サニタイズ (パス トラバーサル/制御文字の拒否)、および非同期エイリアス ゲッター サポートによるモデル情報解決。 | -| `accountFallback.ts` | レート制限の処理: 指数関数的バックオフ (1 秒 → 2 秒 → 4 秒 → 最大 2 分)、アカウントのクールダウン管理、エラー分類 (どのエラーがフォールバックをトリガーするのか、トリガーしないのか)。 | -| `tokenRefresh.ts` | **すべてのプロバイダ**の OAuth トークン更新: Google (Gemini、Antigravity)、Claude、Codex、Qwen、iFlow、GitHub (OAuth + Copilot デュアル トークン)、Kiro (AWS SSO OIDC + Social Auth)。実行中の Promise 重複排除キャッシュと指数バックオフによる再試行が含まれます。 | -| `combo.ts` | **コンボ モデル**: フォールバック モデルのチェーン。モデル A がフォールバック対象エラーで失敗した場合は、モデル B、次にモデル C などを試します。実際のアップストリーム ステータス コードを返します。 | -| `usage.ts` | プロバイダー API からクォータ/使用量データを取得します (GitHub Copilot クォータ、反重力モデル クォータ、Codex レート制限、Kiro 使用量の内訳、Claude 設定)。 | -| `accountSelector.ts` | スコアリング アルゴリズムを使用したスマートなアカウント選択: 優先度、健全性ステータス、ラウンドロビン ポジション、クールダウン状態を考慮して、各リクエストに最適なアカウントを選択します。 | -| `contextManager.ts` | リクエスト コンテキストのライフサイクル管理: デバッグとロギングのために、メタデータ (リクエスト ID、タイムスタンプ、プロバイダー情報) を含むリクエストごとのコンテキスト オブジェクトを作成および追跡します。 | -| `ipFilter.ts` | IP ベースのアクセス制御: ホワイトリスト モードとブロックリスト モードをサポートします。 API リクエストを処理する前に、設定されたルールに照らしてクライアント IP を検証します。 | -| `sessionManager.ts` | クライアント フィンガープリントによるセッション追跡: ハッシュされたクライアント ID を使用してアクティブなセッションを追跡し、リクエスト数を監視し、セッション メトリックを提供します。 | -| `signatureCache.ts` | リクエスト署名ベースの重複排除キャッシュ: 最近のリクエスト署名をキャッシュし、時間枠内の同一リクエストに対してキャッシュされた応答を返すことで、リクエストの重複を防ぎます。 | -| `systemPrompt.ts` | グローバル システム プロンプト インジェクション: プロバイダーごとの互換性処理を使用して、構成可能なシステム プロンプトをすべてのリクエストの先頭または末尾に追加します。 | -| `thinkingBudget.ts` | 推論トークンの予算管理: 思考/推論トークンを制御するためのパススルー、自動 (ストリップ思考構成)、カスタム (固定予算)、および適応型 (複雑さスケール) モードをサポートします。 | -| `wildcardRouter.ts` | ワイルドカード モデル パターン ルーティング: 可用性と優先度に基づいて、ワイルドカード パターン (`*/claude-*` など) を具体的なプロバイダー/モデルのペアに解決します。 | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### トークンのリフレッシュの重複排除 +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### アカウント フォールバック ステート マシン +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### コンボ モデル チェーン +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 トランスレータ (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -自己登録プラグイン システムを使用した **フォーマット変換エンジン**。 +The **format translation engine** using a self-registering plugin system. -#### アーキテクチャ +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| ディレクトリ | ファイル | 説明 | -| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 翻訳者8名 | リクエストボディをフォーマット間で変換します。各ファイルは、インポート時に `register(from, to, fn)` を介して自己登録されます。 | -| `response/` | 翻訳者 7 名 | ストリーミング応答チャンクをフォーマット間で変換します。 SSE イベント タイプ、思考ブロック、ツール呼び出しを処理します。 | -| `helpers/` | 6人のヘルパー | 共有ユーティリティ: `claudeHelper` (システム プロンプト抽出、シンキング構成)、`geminiHelper` (パーツ/コンテンツ マッピング)、`openaiHelper` (フォーマット フィルタリング)、`toolCallHelper` (ID 生成、欠落応答挿入)、`maxTokensHelper`、`responsesApiHelper`。 | -| `index.ts` | — | 変換エンジン: `translateRequest()`、`translateResponse()`、状態管理、レジストリ。 | -| `formats.ts` | — | フォーマット定数: `OPENAI`、`CLAUDE`、`GEMINI`、`ANTIGRAVITY`、`KIRO`、`CURSOR`、`OPENAI_RESPONSES`。 | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### 主な設計: 自己登録プラグイン +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 ユーティリティ (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| ファイル | 目的 | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | エラー応答の構築 (OpenAI 互換形式)、アップストリーム エラー解析、エラー メッセージからの反重力再試行時間の抽出、SSE エラー ストリーミング。 | -| `stream.ts` | **SSE Transform Stream** — コア ストリーミング パイプライン。 2 つのモード: `TRANSLATE` (完全な形式の変換) と `PASSTHROUGH` (正規化 + 使用法の抽出)。チャンクのバッファリング、使用量の推定、コンテンツの長さの追跡を処理します。ストリームごとのエンコーダ/デコーダ インスタンスは共有状態を回避します。 | -| `streamHelpers.ts` | 低レベル SSE ユーティリティ: `parseSSELine` (ホワイトスペース耐性)、`hasValuableContent` (OpenAI/Claude/Gemini の空のチャンクをフィルタリング)、`fixInvalidId`、`formatSSE` (`perf_metrics` クリーンアップによる形式認識 SSE シリアル化)。 | -| `usageTracking.ts` | 任意の形式 (Claude/OpenAI/Gemini/Responses) からのトークン使用量の抽出、別個のツール/メッセージの文字数とトークンの比率による推定、バッファーの追加 (2000 トークンの安全マージン)、形式固有のフィールド フィルタリング、ANSI カラーでのコンソール ロギング。 | -| `requestLogger.ts` | ファイルベースのリクエストログ (`ENABLE_REQUEST_LOGS=true` によるオプトイン)。番号付きファイルを含むセッション フォルダーを作成します: `1_req_client.json` → `7_res_client.txt`。すべての I/O は非同期 (ファイア アンド フォーゲット) です。機密ヘッダーをマスクします。 | -| `bypassHandler.ts` | Claude CLI からの特定のパターン (タイトル抽出、ウォームアップ、カウント) を傍受し、プロバイダーを呼び出さずに偽の応答を返します。ストリーミングと非ストリーミングの両方をサポートします。意図的に Claude CLI スコープに限定されています。 | -| `networkProxy.ts` | 指定されたプロバイダーの送信プロキシ URL を優先順位で解決します: プロバイダー固有の構成 → グローバル構成 → 環境変数 (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`)。 `NO_PROXY` の除外をサポートします。設定を 30 秒間キャッシュします。 | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### SSE ストリーミング パイプライン +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### リクエスト ロガー セッション構造 +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 アプリケーション層 (`src/`) +### 4.7 Application Layer (`src/`) -| ディレクトリ | 目的 | -| ------------- | ---------------------------------------------------------------------------- | -| `src/app/` | Web UI、API ルート、Express ミドルウェア、OAuth コールバック ハンドラー | -| `src/lib/` | データベース アクセス (`localDb.ts`、`usageDb.ts`)、認証、共有 | -| `src/mitm/` | プロバイダーのトラフィックを傍受する中間者プロキシ ユーティリティ | -| `src/models/` | データベースモデルの定義 | -| `src/shared/` | open-sse 関数 (プロバイダー、ストリーム、エラーなど) のラッパー | -| `src/sse/` | open-sse ライブラリを Express ルートに接続する SSE エンドポイント ハンドラー | -| `src/store/` | アプリケーション状態管理 | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### 注目すべき API ルート +#### Notable API Routes -| ルート | メソッド | 目的 | -| --------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | 取得/投稿/削除 | プロバイダーごとのカスタム モデルの CRUD | -| `/api/models/catalog` | 入手 | プロバイダーごとにグループ化されたすべてのモデル (チャット、埋め込み、イメージ、カスタム) の集約カタログ | -| `/api/settings/proxy` | 取得/挿入/削除 | 階層型送信プロキシ構成 (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | 投稿 | プロキシ接続を検証し、パブリック IP/遅延を返します。 | -| `/v1/providers/[provider]/chat/completions` | 投稿 | モデル検証を備えたプロバイダーごとの専用チャット補完 | -| `/v1/providers/[provider]/embeddings` | 投稿 | モデル検証を備えたプロバイダーごとの専用埋め込み | -| `/v1/providers/[provider]/images/generations` | 投稿 | モデル検証を備えたプロバイダーごとの専用イメージ生成 | -| `/api/settings/ip-filter` | GET/PUT | IP ホワイトリスト/ブロックリスト管理 | -| `/api/settings/thinking-budget` | GET/PUT | 推論トークンの予算構成 (パススルー/自動/カスタム/アダプティブ) | -| `/api/settings/system-prompt` | GET/PUT | すべてのリクエストに対するグローバル システム プロンプト インジェクション | -| `/api/sessions` | 入手 | アクティブなセッションの追跡とメトリクス | -| `/api/rate-limits` | 入手 | アカウントごとのレート制限ステータス | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. 主要な設計パターン +## 5. Key Design Patterns -### 5.1 ハブアンドスポーク変換 +### 5.1 Hub-and-Spoke Translation -すべての形式は **OpenAI 形式をハブ**として変換します。新しいプロバイダーを追加するには、N ペアではなく、**1 ペア** のトランスレーター (OpenAI との間) を作成するだけで済みます。 +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 エグゼキューター戦略パターン +### 5.2 Executor Strategy Pattern -各プロバイダーには、`BaseExecutor` を継承する専用の実行クラスがあります。 `executors/index.ts` のファクトリは、実行時に正しいものを選択します。 +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 自己登録プラグイン システム +### 5.3 Self-Registering Plugin System -トランスレータ モジュールは、インポート時に `register()` を介して自身を登録します。新しいトランスレータを追加するには、ファイルを作成してインポートするだけです。 +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 指数関数的バックオフによるアカウントのフォールバック +### 5.4 Account Fallback with Exponential Backoff -プロバイダーが 429/401/500 を返すと、システムは次のアカウントに切り替えて、指数関数的なクールダウン (1 秒 → 2 秒 → 4 秒 → 最大 2 分) を適用できます。 +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 コンボモデルチェーン +### 5.5 Combo Model Chains -「コンボ」は、複数の `provider/model` 文字列をグループ化します。最初の処理が失敗した場合は、自動的に次の処理にフォールバックします。 +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 ステートフル ストリーミング変換 +### 5.6 Stateful Streaming Translation -応答の変換は、`initState()` メカニズムを介して、SSE チャンク全体 (思考ブロックの追跡、ツール呼び出しの蓄積、コンテンツ ブロックのインデックス作成) の状態を維持します。 +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 使用安全バッファー +### 5.7 Usage Safety Buffer -システム プロンプトや形式変換によるオーバーヘッドによってクライアントがコンテキスト ウィンドウの制限に達するのを防ぐために、報告された使用量に 2000 トークンのバッファーが追加されます。 +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. サポートされている形式 +## 6. Supported Formats -| フォーマット | 方向 | 識別子 | -| --------------------- | ------------------- | ------------------ | -| OpenAI チャットの完了 | ソース + ターゲット | `openai` | -| OpenAI レスポンス API | ソース + ターゲット | `openai-responses` | -| 人間のクロード | ソース + ターゲット | `claude` | -| Google ジェミニ | ソース + ターゲット | `gemini` | -| Google Gemini CLI | ターゲットのみ | `gemini-cli` | -| 反重力 | ソース + ターゲット | `antigravity` | -| AWS キロ | ターゲットのみ | `kiro` | -| カーソル | ターゲットのみ | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. サポートされているプロバイダー +## 7. Supported Providers -| プロバイダー | 認証方法 | 執行者 | 重要なメモ | -| ------------------------ | ----------------------------- | ------------ | ----------------------------------------------------------- | -| 人間のクロード | API キーまたは OAuth | デフォルト | `x-api-key` ヘッダーを使用します。 | -| Google ジェミニ | API キーまたは OAuth | デフォルト | `x-goog-api-key` ヘッダーを使用します。 | -| Google Gemini CLI | OAuth | ジェミニCLI | `streamGenerateContent` エンドポイントを使用します。 | -| 反重力 | OAuth | 反重力 | マルチ URL フォールバック、カスタム再試行解析 | -| オープンAI | APIキー | デフォルト | 標準ベアラー認証 | -| コーデックス | OAuth | コーデックス | システム命令を注入し、思考を管理します | -| GitHub コパイロット | OAuth + コパイロット トークン | ギットハブ | デュアル トークン、VSCode ヘッダーの模倣 | -| キロ (AWS) | AWS SSO OIDC またはソーシャル | キロ | バイナリ EventStream 解析 | -| カーソルIDE | チェックサム認証 | カーソル | Protobuf エンコーディング、SHA-256 チェックサム | -| クウェン | OAuth | デフォルト | 標準認証 | -| iFlow | OAuth (ベーシック + ベアラー) | デフォルト | デュアル認証ヘッダー | -| オープンルーター | APIキー | デフォルト | 標準ベアラー認証 | -| GLM、キミ、ミニマックス | APIキー | デフォルト | Claude と互換性があるため、`x-api-key` を使用してください。 | -| `openai-compatible-*` | APIキー | デフォルト | 動的: 任意の OpenAI 互換エンドポイント | -| `anthropic-compatible-*` | APIキー | デフォルト | 動的: クロードと互換性のある任意のエンドポイント | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. データフローの概要 +## 8. Data Flow Summary -### ストリーミングリクエスト +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### 非ストリーミングリクエスト +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### バイパス フロー (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/ja/FEATURES.md b/docs/i18n/ja/FEATURES.md index 19e6235740..82cc73b67b 100644 --- a/docs/i18n/ja/FEATURES.md +++ b/docs/i18n/ja/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — ダッシュボード機能ギャラリー +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -OmniRoute ダッシュボードの各セクションへの視覚的なガイド。 +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 プロバイダー +## 🔌 Providers -AI プロバイダー接続の管理: OAuth プロバイダー (Claude Code、Codex、Gemini CLI)、API キー プロバイダー (Groq、DeepSeek、OpenRouter)、および無料プロバイダー (iFlow、Qwen、Kiro)。 +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 コンボ +## 🎨 Combos -フィルファースト、ラウンドロビン、2 つのべき乗、ランダム、最小使用、コスト最適化の 6 つの戦略を使用してモデル ルーティング コンボを作成します。各コンボは、自動フォールバックを使用して複数のモデルをチェーンします。 +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 分析 +## 📊 Analytics -トークン消費量、コスト見積もり、アクティビティヒートマップ、週次分布グラフ、プロバイダーごとの内訳を含む包括的な使用状況分析。 +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 システムの健全性 +## 🏥 System Health -リアルタイム監視: 稼働時間、メモリ、バージョン、遅延パーセンタイル (p50/p95/p99)、キャッシュ統計、プロバイダーのサーキット ブレーカーの状態。 +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 翻訳者の遊び場 +## 🔧 Translator Playground -API 変換をデバッグするための 4 つのモード: **プレイグラウンド** (フォーマット コンバーター)、**チャット テスター** (ライブ リクエスト)、**テスト ベンチ** (バッチ テスト)、**ライブ モニター** (リアルタイム ストリーム)。 +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ 設定 +## 🎮 Model Playground _(v2.0.9+)_ -一般設定、システム ストレージ、バックアップ管理 (データベースのエクスポート/インポート)、外観 (ダーク/ライト モード)、セキュリティ (API エンドポイント保護とカスタム プロバイダーのブロックを含む)、ルーティング、復元力、および詳細な構成。 +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI ツール +## 🔧 CLI Tools -AI コーディング ツールのワンクリック構成: Claude Code、Codex CLI、Gemini CLI、OpenClaw、Kilo Code、Antigravity。 +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 リクエストログ +## 🤖 CLI Agents _(v2.0.11+)_ -プロバイダー、モデル、アカウント、API キーによるフィルタリングを備えたリアルタイムのリクエストログ。ステータス コード、トークンの使用状況、待ち時間、応答の詳細を表示します。 +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API エンドポイント +## 🌐 API Endpoint -機能の内訳を含む統合 API エンドポイント: チャット完了、埋め込み、画像生成、再ランキング、音声文字起こし、登録された API キー。 +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ja/TROUBLESHOOTING.md b/docs/i18n/ja/TROUBLESHOOTING.md index 7b3176ccd2..120092d63c 100644 --- a/docs/i18n/ja/TROUBLESHOOTING.md +++ b/docs/i18n/ja/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# トラブルシューティング +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -OmniRoute の一般的な問題と解決策。 +Common problems and solutions for OmniRoute. --- -## クイックフィックス +## Quick Fixes -| 問題 | ソリューション | -| ----------------------------------------- | ------------------------------------------------------------------------------- | -| 最初のログインが機能しない | `.env` の `INITIAL_PASSWORD` を確認します (デフォルト: `123456`)。 | -| ダッシュボードが間違ったポートで開きます | `PORT=20128` と `NEXT_PUBLIC_BASE_URL=http://localhost:20128` を設定します。 | -| `logs/` の下にリクエスト ログがありません | `ENABLE_REQUEST_LOGS=true` を設定 | -| EACCES: 許可が拒否されました | `DATA_DIR=/path/to/writable/dir` を設定して `~/.omniroute` をオーバーライドする | -| ルーティング戦略が保存されない | v1.4.11+ に更新 (設定永続性のための Zod スキーマ修正) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## プロバイダーの問題 +## Provider Issues -### 「言語モデルがメッセージを提供しませんでした」 +### "Language model did not provide messages" -**原因:** プロバイダーの割り当てが枯渇しました。 +**Cause:** Provider quota exhausted. -**修正:** +**Fix:** -1. ダッシュボードのクォータ トラッカーを確認する -2. フォールバック層とのコンボを使用する -3. より安価な/無料枠に切り替える +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### レート制限 +### Rate Limiting -**原因:** サブスクリプション割り当てを使い果たしました。 +**Cause:** Subscription quota exhausted. -**修正:** +**Fix:** -- フォールバックを追加: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- 安価なバックアップとして GLM/MiniMax を使用する +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth トークンの有効期限が切れました +### OAuth Token Expired -OmniRoute はトークンを自動更新します。問題が解決しない場合: +OmniRoute auto-refreshes tokens. If issues persist: -1. ダッシュボード → プロバイダー → 再接続 -2. プロバイダー接続を削除して再度追加します。 +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## クラウドの問題 +## Cloud Issues -### クラウド同期エラー +### Cloud Sync Errors -1. `BASE_URL` が実行中のインスタンス (例: `http://localhost:20128`) を指していることを確認します。 -2. `CLOUD_URL` がクラウド エンドポイント (例: `https://omniroute.dev`) を指していることを確認します。 -3. `NEXT_PUBLIC_*` 値をサーバー側の値と一致させておく +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### クラウド `stream=false` は 500 を返します +### Cloud `stream=false` Returns 500 -**症状:** 非ストリーミング通話のクラウド エンドポイントで `Unexpected token 'd'...` が発生します。 +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**原因:** クライアントが JSON を期待しているのに、アップストリームは SSE ペイロードを返します。 +**Cause:** Upstream returns SSE payload while client expects JSON. -**回避策:** クラウド直接呼び出しには `stream=true` を使用します。ローカル ランタイムには SSE→JSON フォールバックが含まれます。 +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### クラウドは接続済みだが「API キーが無効です」と表示します +### Cloud Says Connected but "Invalid API key" -1. ローカル ダッシュボードから新しいキーを作成します (`/api/keys`) -2. クラウド同期を実行します: [クラウドを有効にする] → [今すぐ同期] -3. 古い/非同期キーはクラウド上でも `401` を返すことができます +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Docker の問題 +## Docker Issues -### CLI ツールがインストールされていないと表示される +### CLI Tool Shows Not Installed -1. 実行時フィールドを確認します: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. ポータブル モードの場合: イメージ ターゲット `runner-cli` (バンドルされた CLI) を使用します。 -3. ホスト マウント モードの場合: `CLI_EXTRA_PATHS` を設定し、ホストの bin ディレクトリを読み取り専用としてマウントします。 -4. `installed=true` および `runnable=false` の場合: バイナリは見つかりましたが、ヘルスチェックに失敗しました +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### 迅速なランタイム検証 +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,21 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## コストの問題 +## Cost Issues -### 高コスト +### High Costs -1.「ダッシュボード」→「使用状況」で使用状況統計を確認します。2. プライマリ モデルを GLM/MiniMax に切り替える 3. 重要ではないタスクには無料枠 (Gemini CLI、iFlow) を使用する 4. API キーごとにコスト予算を設定します: [ダッシュボード] → [API キー] → [予算] +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## デバッグ +## Debugging -### リクエストログを有効にする +### Enable Request Logs -`.env` ファイルに `ENABLE_REQUEST_LOGS=true` を設定します。ログは `logs/` ディレクトリの下に表示されます。 +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### プロバイダーの健全性を確認する +### Check Provider Health ```bash # Health dashboard @@ -115,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### ランタイムストレージ +### Runtime Storage -- メイン状態: `${DATA_DIR}/db.json` (プロバイダー、コンボ、エイリアス、キー、設定) -- 使用法: `${DATA_DIR}/usage.json`、`${DATA_DIR}/log.txt`、`${DATA_DIR}/call_logs/` -- リクエストログ：`/logs/...`（`ENABLE_REQUEST_LOGS=true`の場合） +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## サーキットブレーカーの問題 +## Circuit Breaker Issues -### プロバイダーが OPEN 状態でスタックしている +### Provider stuck in OPEN state -プロバイダーのサーキット ブレーカーが OPEN の場合、リクエストはクールダウンが期限切れになるまでブロックされます。 +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**修正:** +**Fix:** -1. **ダッシュボード → 設定 → レジリエンス** に移動します -2. 影響を受けるプロバイダーのサーキット ブレーカー カードを確認します。 -3. [**すべてリセット**] をクリックしてすべてのブレーカーをクリアするか、クールダウンが期限切れになるまで待ちます。 -4. リセットする前に、プロバイダーが実際に利用可能であることを確認します。 +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### プロバイダーがサーキットブレーカーを落とし続けます +### Provider keeps tripping the circuit breaker -プロバイダーが繰り返し OPEN 状態になる場合: +If a provider repeatedly enters OPEN state: -1. **ダッシュボード → ヘルス → プロバイダーのヘルス** で障害パターンを確認します。 -2. **[設定] → [復元力] → [プロバイダー プロファイル]** に移動し、失敗のしきい値を増やします。 -3. プロバイダーが API 制限を変更したか、再認証が必要かどうかを確認します。 -4. レイテンシーテレメトリを確認します - レイテンシーが長いとタイムアウトベースのエラーが発生する可能性があります +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## 音声文字起こしの問題 +## Audio Transcription Issues -### 「サポートされていないモデル」エラー +### "Unsupported model" error -- 正しいプレフィックスを使用していることを確認してください: `deepgram/nova-3` または `assemblyai/best` -- **「ダッシュボード」→「プロバイダー」**でプロバイダーが接続されていることを確認します。 +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### 文字起こしが空を返すか失敗する +### Transcription returns empty or fails -- サポートされているオーディオ形式を確認します: `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm` -- ファイル サイズがプロバイダーの制限内であることを確認します (通常は < 25MB) -- プロバイダー カードのプロバイダー API キーの有効性を確認します。 +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## トランスレータのデバッグ +## Translator Debugging -**ダッシュボード → トランスレーター** を使用して、形式変換の問題をデバッグします。 +Use **Dashboard → Translator** to debug format translation issues: -| モード | いつ使用するか | -| --------------------- | ----------------------------------------------------------------------------------------------------------- | -| **遊び場** | 入力/出力形式を並べて比較します。失敗したリクエストを貼り付けて、それがどのように変換されるかを確認します。 | -| **チャット テスター** | ライブ メッセージを送信し、ヘッダーを含む完全なリクエスト/レスポンス ペイロードを検査します。 | -| **テストベンチ** | フォーマットの組み合わせ全体でバッチ テストを実行して、どの翻訳が壊れているかを見つけます。 | -| **ライブモニター** | リアルタイムのリクエスト フローを監視して断続的な翻訳の問題を検出 | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### 一般的な形式の問題 +### Common format issues -- **思考タグが表示されない** — ターゲットプロバイダーが思考と思考予算設定をサポートしているかどうかを確認してください -- **ツール呼び出しのドロップ** — 一部の形式変換では、サポートされていないフィールドが削除される場合があります。プレイグラウンド モードで確認する -- **システム プロンプトがありません** — クロードとジェミニはシステム プロンプトの処理方法が異なります。翻訳出力を確認する -- **SDK はオブジェクトではなく生の文字列を返します** — v1.1.0 で修正されました: 応答サニタイザーは、OpenAI SDK Pydantic 検証エラーの原因となる非標準フィールド (`x_groq`、`usage_breakdown` など) を削除するようになりました。 -- **GLM/ERNIE が `system` ロールを拒否します** — v1.1.0 で修正: ロール ノーマライザーは、互換性のないモデルのシステム メッセージをユーザー メッセージに自動的にマージします -- **`developer` ロールが認識されない** — v1.1.0 で修正: 非 OpenAI プロバイダーの場合は自動的に `system` に変換されます -- **`json_schema` が Gemini で動作しない** — v1.1.0 で修正: `response_format` は Gemini の `responseMimeType` + `responseSchema` に変換されるようになりました。 +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## 復元力の設定 +## Resilience Settings -### 自動レート制限がトリガーされない +### Auto rate-limit not triggering -- 自動レート制限は API キープロバイダーにのみ適用されます (OAuth/サブスクリプションには適用されません) -- **設定 → 復元力 → プロバイダー プロファイル** で自動レート制限が有効になっていることを確認します -- プロバイダーが `429` ステータス コードまたは `Retry-After` ヘッダーを返すかどうかを確認します。 +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### 指数バックオフの調整 +### Tuning exponential backoff -プロバイダー プロファイルは次の設定をサポートします。 +Provider profiles support these settings: -- **基本遅延** — 最初の失敗後の初期待機時間 (デフォルト: 1 秒) -- **最大遅延** — 最大待機時間の上限 (デフォルト: 30 秒) -- **乗数** — 連続した失敗ごとにどれだけ遅延を増加させるか (デフォルト: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### 対雷の群れ +### Anti-thundering herd -多くの同時リクエストがレート制限プロバイダーに到達すると、OmniRoute はミューテックスと自動レート制限を使用してリクエストをシリアル化し、連鎖的な失敗を防ぎます。これは API キープロバイダーの場合は自動的に行われます。 +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## まだ行き詰まっていますか? +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub の問題**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **アーキテクチャ**: 内部の詳細については、[link](ARCHITECTURE.md) を参照してください。 -- **API リファレンス**: すべてのエンドポイントについては、[link](API_REFERENCE.md) を参照してください。 -- **ヘルス ダッシュボード**: リアルタイムのシステム ステータスについては、**ダッシュボード → ヘルス** を確認してください。 -- **トランスレータ**: **ダッシュボード → トランスレータ**を使用して形式の問題をデバッグします +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/ja/USER_GUIDE.md b/docs/i18n/ja/USER_GUIDE.md index a24bb408e1..5a043224df 100644 --- a/docs/i18n/ja/USER_GUIDE.md +++ b/docs/i18n/ja/USER_GUIDE.md @@ -1,12 +1,12 @@ -# ユーザーガイド +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -プロバイダーの構成、コンボの作成、CLI ツールの統合、OmniRoute の展開に関する完全なガイド。 +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## 目次 +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 価格の概要 +## 💰 Pricing at a Glance -| 階層 | プロバイダー | コスト | クォータのリセット | 最適な用途 | -| ------------------------- | -------------------------- | --------------------- | ------------------- | ---------------------- | -| **💳 サブスクリプション** | クロード・コード (プロ) | $20/月 | 5 時間 + 毎週 | すでに購読済み | -| | コーデックス (プラス/プロ) | $20-200/月 | 5 時間 + 毎週 | OpenAI ユーザー | -| | ジェミニ CLI | **無料** | 180K/月 + 1K/日 | みんな！ | -| | GitHub コパイロット | $10-19/月 | 月刊 | GitHub ユーザー | -| **🔑 API キー** | ディープシーク | 使用ごとに支払い | なし | 安っぽい推論 | -| | グロク | 使用ごとに支払い | なし | 超高速推論 | -| | xAI (グロック) | 使用ごとに支払い | なし | Grok 4 の推論 | -| | ミストラル | 使用ごとに支払い | なし | EU がホストするモデル | -| | 困惑 | 使用ごとに支払い | なし | 検索拡張 | -| | 一緒にAI | 使用ごとに支払い | なし | オープンソース モデル | -| | 花火AI | 使用ごとに支払い | なし | 高速 FLUX 画像 | -| | 大脳 | 使用ごとに支払い | なし | ウェーハスケールの速度 | -| | コヒア | 使用ごとに支払い | なし | コマンド R+ RAG | -| | NVIDIA NIM | 使用ごとに支払い | なし | エンタープライズモデル | -| **💰安い** | GLM-4.7 | $0.6/100万 | 毎日午前 10 時 | 予算のバックアップ | -| | ミニマックス M2.1 | $0.2/100万 | 5時間ローリング | 最も安いオプション | -| | キミ K2 | 月額 9 ドルのフラット | 1,000 万トークン/月 | 予測可能なコスト | -| **🆓 無料** | iFlow | $0 | 無制限 | 8 モデルは無料 | -| | クウェン | $0 | 無制限 | 3 モデルは無料 | -| | キロ | $0 | 無制限 | クロード・フリー | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 プロのヒント:** Gemini CLI (180,000 無料/月) + iFlow (無制限の無料) コンボ = コスト 0 ドルから始めましょう! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 使用例 +## 🎯 Use Cases -### ケース 1: 「Claude Pro サブスクリプションを持っています」 +### Case 1: "I have Claude Pro subscription" -**問題:** 大量のコーディング中にクォータが使用されずに期限切れになり、レート制限が発生する +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### ケース 2: 「コストをゼロにしたい」 +### Case 2: "I want zero cost" -**問題:** サブスクリプションを購入する余裕がないため、信頼性の高い AI コーディングが必要です +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### ケース 3: 「24 時間年中無休でコーディングが必要で、中断はありません」 +### Case 3: "I need 24/7 coding, no interruptions" -**問題:** 締め切りが迫っており、ダウンタイムを許すことができません +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### ケース 4: 「OpenClaw に無料の AI が欲しい」 +### Case 4: "I want FREE AI in OpenClaw" -**問題:** メッセージング アプリには AI アシスタントが必要ですが、完全に無料です +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 プロバイダーのセットアップ +## 📖 Provider Setup -### 🔐 サブスクリプションプロバイダー +### 🔐 Subscription Providers -#### クロード コード (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**プロのヒント:** 複雑なタスクには Opus を使用し、速度を求める場合は Sonnet を使用します。 OmniRoute はモデルごとの割り当てを追跡します。 +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (月額 180,000 が無料!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**ベストバリュー:** 膨大な無料枠!有料レベルの前にこれを使用してください。 +**Best Value:** Huge free tier! Use this before paid tiers. -#### GitHub コパイロット +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,32 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 格安プロバイダー +### 💰 Cheap Providers -#### GLM-4.7 (毎日リセット、0.6 ドル/100 万ドル) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. サインアップ: [Zhipu AI](https://open.bigmodel.cn/) 2.コーディングプランからAPIキーを取得 -2. ダッシュボード → API キーの追加: プロバイダー: `glm`、API キー: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**使用方法:** `glm/glm-4.7` — **プロのヒント:** コーディング プランでは、1/7 のコストで 3 倍のクォータを提供します。毎日午前 10 時にリセットされます。 +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 時間リセット、$0.20/1M) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. サインアップ: [MiniMax](https://www.minimax.io/) -2. APIキーの取得 → ダッシュボード → APIキーの追加 +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**使用方法:** `minimax/MiniMax-M2.1` — **プロのヒント:** 長いコンテキスト (100 万トークン) の最も安価なオプション! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### キミ K2 (月額一律 9 ドル) +#### Kimi K2 ($9/month flat) -1. 購読: [Moonshot AI](https://platform.moonshot.ai/) -2. APIキーの取得 → ダッシュボード → APIキーの追加 +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**使用方法:** `kimi/kimi-latest` — **プロのヒント:** 1,000 万トークンの固定 $9/月 = 0.90 ドル/100 万の実効コスト! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 無料プロバイダー +### 🆓 FREE Providers -#### iFlow (8 つの無料モデル) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -200,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 つの無料モデル) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -208,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### キロ (クロード フリー) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -218,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 コンボ +## 🎨 Combos -### 例 1: サブスクリプションを最大化 → 安価なバックアップ +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -234,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### 例 2: 無料のみ (コストゼロ) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -248,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI の統合 +## 🔧 CLI Integration -### カーソル IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -259,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### クロードコード +### Claude Code -`~/.claude/config.json` を編集します: +Edit `~/.claude/config.json`: ```json { @@ -270,7 +271,7 @@ Settings → Models → Advanced: } ``` -### コーデックス CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -278,9 +279,9 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### オープンクロー +### OpenClaw -`~/.openclaw/openclaw.json` を編集します: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -302,9 +303,9 @@ codex "your prompt" } ``` -**またはダッシュボードを使用します:** CLI ツール → OpenClaw → 自動構成 +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### クライン / 継続 / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -315,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 導入 +## 🚀 Deployment -### VPS 導入 +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -336,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### ドッカー +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -346,69 +403,72 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -CLI バイナリを使用したホスト統合モードについては、メイン ドキュメントの Docker セクションを参照してください。 +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### 環境変数 +### Environment Variables -| 変数 | デフォルト | 説明 | -| --------------------- | ------------------------------------ | ----------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 署名シークレット (**本番環境での変更**) | -| `INITIAL_PASSWORD` | `123456` | 初回ログインパスワード | -| `DATA_DIR` | `~/.omniroute` | データ ディレクトリ (データベース、使用状況、ログ) | -| `PORT` | フレームワークのデフォルト | サービスポート (例では `20128`) | -| `HOSTNAME` | フレームワークのデフォルト | バインド ホスト (Docker のデフォルトは `0.0.0.0`) | -| `NODE_ENV` | 実行時のデフォルト | デプロイ用に `production` を設定 | -| `BASE_URL` | `http://localhost:20128` | サーバー側の内部ベース URL | -| `CLOUD_URL` | `https://omniroute.dev` | クラウド同期エンドポイントのベース URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | 生成された API キーの HMAC シークレット | -| `REQUIRE_API_KEY` | `false` | `/v1/*` にベアラー API キーを強制する | -| `ENABLE_REQUEST_LOGS` | `false` | リクエスト/レスポンスログを有効にする | -| `AUTH_COOKIE_SECURE` | `false` | `Secure` 認証 Cookie を強制する (HTTPS リバース プロキシの背後で) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -環境変数の完全なリファレンスについては、[README](../README.md) を参照してください。 +For the full environment variable reference, see the [README](../README.md). --- -## 📊 利用可能なモデル +## 📊 Available Models
-利用可能なモデルをすべて表示 +View all available models -**クロード コード (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`、`cc/claude-sonnet-4-5-20250929`、`cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**コーデックス (`cx/`)** — プラス/プロ: `cx/gpt-5.2-codex`、`cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — 無料: `gc/gemini-3-flash-preview`、`gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**GitHub コパイロット (`gh/`)**: `gh/gpt-5`、`gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` **GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` **MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — 無料: `if/kimi-k2-thinking`、`if/qwen3-coder-plus`、`if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**クウェン (`qw/`)** — 無料: `qw/qwen3-coder-plus`、`qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**キロ (`kr/`)** — 無料: `kr/claude-sonnet-4.5`、`kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` -**ディープシーク (`ds/`)**: `ds/deepseek-chat`、`ds/deepseek-reasoner` +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` -**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`、`groq/llama-4-maverick-17b-128e-instruct` +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` -**xAI (`xai/`)**: `xai/grok-4`、`xai/grok-4-0709-fast-reasoning`、`xai/grok-code-mini` +**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**ミストラル (`mistral/`)**: `mistral/mistral-large-2501`、`mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**混乱 (`pplx/`)**: `pplx/sonar-pro`、`pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**一緒に AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**花火 AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**セレブ (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**ここにあります (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -416,11 +476,11 @@ CLI バイナリを使用したホスト統合モードについては、メイ --- -## 🧩 高度な機能 +## 🧩 Advanced Features -### カスタムモデル +### Custom Models -アプリの更新を待たずに、任意のモデル ID を任意のプロバイダーに追加します。 +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -432,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -または、ダッシュボードを使用します: **プロバイダー → [プロバイダー] → カスタム モデル**。 +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### 専用プロバイダー ルート +### Dedicated Provider Routes -モデル検証を使用してリクエストを特定のプロバイダーに直接ルーティングします。 +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -444,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -プロバイダーのプレフィックスが存在しない場合は、自動的に追加されます。モデルが一致しない場合は、`400` が返されます。 +The provider prefix is auto-added if missing. Mismatched models return `400`. -### ネットワークプロキシ構成 +### Network Proxy Configuration ```bash # Set global proxy @@ -462,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**優先順位:** キー固有 → コンボ固有 → プロバイダー固有 → グローバル → 環境。 +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### モデル カタログ API +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -タイプ (`chat`、`embedding`、`image`) を持つプロバイダーごとにグループ化されたモデルを返します。 +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### クラウド同期 +### Cloud Sync -- デバイス間でプロバイダー、コンボ、設定を同期します -- タイムアウト + フェイルファストによる自動バックグラウンド同期 -- 運用環境ではサーバー側の `BASE_URL`/`CLOUD_URL` を優先します +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM ゲートウェイ インテリジェンス (フェーズ 9) +### LLM Gateway Intelligence (Phase 9) -- **セマンティック キャッシュ** — 非ストリーミング、温度=0 の応答を自動キャッシュします (`X-OmniRoute-No-Cache: true` によるバイパス) -- **リクエストのべき等性** — `Idempotency-Key` または `X-Request-Id` ヘッダーを介して 5 秒以内にリクエストの重複を排除します。 -- **進行状況の追跡** — `X-OmniRoute-Progress: true` ヘッダーを介した SSE `event: progress` イベントのオプトイン +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### 翻訳者の遊び場 +### Translator Playground -**ダッシュボード → トランスレーター** からアクセスします。 OmniRoute がプロバイダー間で API リクエストをどのように変換するかをデバッグして視覚化します。 +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| モード | 目的 | -| --------------------- | --------------------------------------------------------------------------------------------- | -| **遊び場** | ソース/ターゲット形式を選択し、リクエストを貼り付けると、翻訳された出力が即座に表示されます。 | -| **チャット テスター** | プロキシ経由でライブ チャット メッセージを送信し、完全な要求/応答サイクルを検査します。 | -| **テストベンチ** | 複数の形式の組み合わせに対してバッチ テストを実行して、翻訳の正確さを検証します。 | -| **ライブモニター** | リクエストがプロキシを通過するときにリアルタイムの翻訳を監視します。 | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**使用例:** +**Use cases:** -- 特定のクライアント/プロバイダーの組み合わせが失敗する理由をデバッグする -- 思考タグ、ツール呼び出し、システム プロンプトが正しく翻訳されていることを確認します。 -- OpenAI、Claude、Gemini、および Responses API 形式間の形式の違いを比較します。 +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### ルーティング戦略 +### Routing Strategies -**[ダッシュボード] → [設定] → [ルーティング]** から設定します。 +Configure via **Dashboard → Settings → Routing**. -| 戦略 | 説明 | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -| **最初に記入してください** | 優先順位に従ってアカウントを使用します。プライマリ アカウントは利用できなくなるまですべてのリクエストを処理します。 | -| **ラウンドロビン** | 設定可能なスティッキー制限を使用して、すべてのアカウントを循環します (デフォルト: アカウントごとに 3 コール)。 | -| **P2C (2 つの選択肢の累乗)** | ランダムな 2 つのアカウントを選択し、より健全なアカウントにルーティングします — 健康を意識しながら負荷のバランスをとります | -| **ランダム** | Fisher-Yates shuffle | を使用してリクエストごとにアカウントをランダムに選択します。 | -| **使用頻度が最も低い** | 最も古い `lastUsedAt` タイムスタンプを持つアカウントにルーティングし、トラフィックを均等に分散します。 | -| **コストの最適化** | 最も低い優先順位の値を持つアカウントにルーティングし、最もコストの低いプロバイダー向けに最適化します。 | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### ワイルドカード モデルのエイリアス +#### Wildcard Model Aliases -ワイルドカード パターンを作成してモデル名を再マッピングします。 +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -ワイルドカードは、`*` (任意の文字) および `?` (単一文字) をサポートします。 +Wildcards support `*` (any characters) and `?` (single character). -#### フォールバック チェーン +#### Fallback Chains -すべてのリクエストに適用されるグローバル フォールバック チェーンを定義します。 +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -542,46 +602,46 @@ Chain: production-fallback --- -### レジリエンスとサーキットブレーカー +### Resilience & Circuit Breakers -**ダッシュボード → 設定 → レジリエンス** から設定します。 +Configure via **Dashboard → Settings → Resilience**. -OmniRoute は、次の 4 つのコンポーネントでプロバイダー レベルの復元力を実装します。 +OmniRoute implements provider-level resilience with four components: -1. **プロバイダー プロファイル** — 以下のプロバイダーごとの構成: - - 失敗しきい値 (開くまでに何回失敗したか) - - クールダウン期間 - - レート制限検出感度 - - 指数バックオフパラメータ +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **編集可能なレート制限** — ダッシュボードで構成可能なシステムレベルのデフォルト: - - **1 分あたりのリクエスト数 (RPM)** — アカウントごとの 1 分あたりの最大リクエスト数 - - **リクエスト間の最小時間** — リクエスト間の最小ギャップ (ミリ秒単位) - - **最大同時リクエスト** — アカウントあたりの最大同時リクエスト - - [**編集**] をクリックして変更し、**保存** または **キャンセル** をクリックします。値は復元 API を介して保持されます。 +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **サーキット ブレーカー** — プロバイダーごとに障害を追跡し、しきい値に達すると自動的に回線を開きます。 - - **クローズ** (正常) — リクエストは正常に流れます - - **OPEN** — プロバイダーは失敗が繰り返された後、一時的にブロックされています - - **HALF_OPEN** — プロバイダーが回復したかどうかをテストします +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **ポリシーとロックされた識別子** — 強制ロック解除機能を備えたサーキット ブレーカーのステータスとロックされた識別子を表示します。 +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **レート制限の自動検出** — `429` ヘッダーと `Retry-After` ヘッダーを監視して、プロバイダーのレート制限に達することを事前に回避します。 +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**プロのヒント:** プロバイダーが停止から回復したときに、**すべてリセット** ボタンを使用して、すべてのサーキット ブレーカーとクールダウンをクリアします。 +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### データベースのエクスポート/インポート +### Database Export / Import -**[ダッシュボード] > [設定] > [システムとストレージ]** でデータベースのバックアップを管理します。 +Manage database backups in **Dashboard → Settings → System & Storage**. -| アクション | 説明 | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| **データベースのエクスポート** | 現在の SQLite データベースを `.sqlite` ファイルとしてダウンロードします。 | -| **すべてエクスポート (.tar.gz)** | データベース、設定、コンボ、プロバイダー接続 (認証情報なし)、API キー メタデータを含む完全なバックアップ アーカイブをダウンロードします。 | -| **データベースのインポート** | `.sqlite` ファイルをアップロードして、現在のデータベースを置き換えます。インポート前のバックアップが自動的に作成されます。 | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -595,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**インポートの検証:** インポートされたファイルは、整合性 (SQLite プラグマ チェック)、必要なテーブル (`provider_connections`、`provider_nodes`、`combos`、`api_keys`)、およびサイズ (最大 100MB) について検証されます。 +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**使用例:** +**Use Cases:** -- マシン間で OmniRoute を移行する -- 災害復旧のために外部バックアップを作成する -- チームメンバー間で設定を共有（すべてエクスポート→アーカイブを共有） +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### 設定ダッシュボード +### Settings Dashboard -設定ページは 5 つのタブで構成されており、簡単にナビゲーションできます。 +The settings page is organized into 5 tabs for easy navigation: -| タブ | 目次 | -| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| **セキュリティ** | ログイン/パスワード設定、IP アクセス制御、`/models` の API 認証、およびプロバイダーのブロック | -| **ルーティング** | グローバル ルーティング戦略 (6 つのオプション)、ワイルドカード モデル エイリアス、フォールバック チェーン、コンボ デフォルト | -| **回復力** | プロバイダー プロファイル、編集可能なレート制限、サーキット ブレーカーのステータス、ポリシー、ロックされた識別子 | -| **AI** | 予算構成、グローバル システム プロンプト インジェクション、プロンプト キャッシュ統計を考える | -| **上級** | グローバル プロキシ構成 (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### コストと予算の管理 +### Costs & Budget Management -**[ダッシュボード] → [コスト]** からアクセスします。 +Access via **Dashboard → Costs**. -| タブ | 目的 | -| -------- | ----------------------------------------------------------------------------------- | -| **予算** | 日次/週次/月次の予算とリアルタイムの追跡を使用して、API キーごとに支出制限を設定 | -| **価格** | モデル価格エントリの表示と編集 - プロバイダーごとの 1K 入出力トークンあたりのコスト | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -638,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**コスト追跡:** すべてのリクエストはトークンの使用状況を記録し、価格表を使用してコストを計算します。 **「ダッシュボード」→「使用状況**」でプロバイダー、モデル、API キーごとの内訳を表示します。 +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### 音声文字起こし +### Audio Transcription -OmniRoute は、OpenAI 互換エンドポイントを介した音声転写をサポートしています。 +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -658,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -利用可能なプロバイダー: **Deepgram** (`deepgram/`)、**AssemblyAI** (`assemblyai/`)。 +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -サポートされている音声形式: `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。 +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### コンボバランス戦略 +### Combo Balancing Strategies -**ダッシュボード → コンボ → 作成/編集 → 戦略** でコンボごとのバランスを設定します。 +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| 戦略 | 説明 | -| ---------------------- | -------------------------------------------------------------------------------- | -| **ラウンドロビン** | モデルを順番に回転します。 | -| **優先度** | 常に最初のモデルを試します。エラーの場合のみフォールバック | -| **ランダム** | 各リクエストのコンボからランダムなモデルを選択します。 | -| **加重** | モデルごとに割り当てられた重みに基づいて比例的にルーティングします。 | -| **使用頻度が最も低い** | 最近のリクエストが最も少ないモデルにルーティングします (コンボ メトリックを使用) | -| **コストの最適化** | 利用可能な最も安価なモデルへのルート (価格表を使用) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -グローバル コンボ デフォルトは、**[ダッシュボード] → [設定] → [ルーティング] → [コンボ デフォルト]** で設定できます。 +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### 健康ダッシュボード +### Health Dashboard -**「ダッシュボード」→「ヘルス」** からアクセスします。 6 枚のカードによるリアルタイムのシステム状態の概要: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| カード | それが示すもの | -| ---------------------------- | -------------------------------------------------------------------------------- | -| **システムステータス** | 稼働時間、バージョン、メモリ使用量、データ ディレクトリ | -| **プロバイダーの状態** | プロバイダーごとのサーキット ブレーカーの状態 (クローズ/オープン/ハーフオープン) | -| **レート制限** | アカウントごとのアクティブなレート制限クールダウンと残り時間 | -| **アクティブなロックアウト** | ロックアウト ポリシーによって一時的にブロックされたプロバイダー | -| **署名キャッシュ** | 重複排除キャッシュの統計 (アクティブなキー、ヒット率) | -| **レイテンシ テレメトリ** | プロバイダーごとの p50/p95/p99 レイテンシの集計 | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**プロのヒント:** [ヘルス] ページは 10 秒ごとに自動更新されます。サーキット ブレーカー カードを使用して、どのプロバイダーで問題が発生しているかを特定します。 +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/ko/API_REFERENCE.md b/docs/i18n/ko/API_REFERENCE.md index 3ba173ce39..b795722c11 100644 --- a/docs/i18n/ko/API_REFERENCE.md +++ b/docs/i18n/ko/API_REFERENCE.md @@ -1,12 +1,12 @@ -# API 참조 +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -모든 OmniRoute API 엔드포인트에 대한 전체 참조입니다. +Complete reference for all OmniRoute API endpoints. --- -## 목차 +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## 채팅 완료 +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### 사용자 정의 헤더 +### Custom Headers -| 헤더 | 방향 | 설명 | -| ------------------------ | ---- | ----------------------------------- | -| `X-OmniRoute-No-Cache` | 요청 | 캐시를 우회하려면 `true`로 설정 | -| `X-OmniRoute-Progress` | 요청 | 진행 이벤트의 경우 `true`으로 설정 | -| `Idempotency-Key` | 요청 | 중복 제거 키(5초 창) | -| `X-Request-Id` | 요청 | 대체 중복 제거 키 | -| `X-OmniRoute-Cache` | 응답 | `HIT` 또는 `MISS`(비스트리밍) | -| `X-OmniRoute-Idempotent` | 응답 | 중복이 제거된 경우 `true` | -| `X-OmniRoute-Progress` | 응답 | `enabled` 진행 상황을 추적하는 경우 | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## 임베딩 +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -사용 가능한 공급자: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## 이미지 생성 +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -사용 가능한 제공업체: OpenAI(DALL-E), xAI(Grok Image), Together AI(FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## 모델 목록 +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## 호환성 끝점 +## Compatibility Endpoints -| 방법 | 경로 | 형식 | -| ------ | --------------------------- | ----------------------- | -| 포스트 | `/v1/chat/completions` | 오픈AI | -| 포스트 | `/v1/messages` | 인류학 | -| 포스트 | `/v1/responses` | OpenAI 응답 | -| 포스트 | `/v1/embeddings` | 오픈AI | -| 포스트 | `/v1/images/generations` | 오픈AI | -| 받기 | `/v1/models` | 오픈AI | -| 포스트 | `/v1/messages/count_tokens` | 인류학 | -| 받기 | `/v1beta/models` | 쌍둥이자리 | -| 포스트 | `/v1beta/models/{...path}` | 쌍둥이 자리 생성 콘텐츠 | -| 포스트 | `/v1/api/chat` | 올라마 | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### 전용 공급자 경로 +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -공급자 접두사가 누락된 경우 자동으로 추가됩니다. 일치하지 않는 모델은 `400`을 반환합니다. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## 시맨틱 캐시 +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -응답 예: +Response example: ```json { @@ -162,154 +162,164 @@ DELETE /api/cache --- -## 대시보드 및 관리 +## Dashboard & Management -### 인증 +### Authentication -| 엔드포인트 | 방법 | 설명 | -| ----------------------------- | ------------- | ---------------- | -| `/api/auth/login` | 포스트 | 로그인 | -| `/api/auth/logout` | 포스트 | 로그아웃 | -| `/api/settings/require-login` | 가져오기/넣기 | 토글 로그인 필요 | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### 공급자 관리 +### Provider Management -| 엔드포인트 | 방법 | 설명 | -| ---------------------------- | ------------------ | ------------------ | -| `/api/providers` | 받기/게시 | 공급자 목록/생성 | -| `/api/providers/[id]` | 가져오기/넣기/삭제 | 공급자 관리 | -| `/api/providers/[id]/test` | 포스트 | 테스트 공급자 연결 | -| `/api/providers/[id]/models` | 받기 | 공급자 모델 나열 | -| `/api/providers/validate` | 포스트 | 공급자 구성 확인 | -| `/api/provider-nodes*` | 다양한 | 공급자 노드 관리 | -| `/api/provider-models` | 가져오기/게시/삭제 | 맞춤형 모델 | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth 흐름 +### OAuth Flows -| 엔드포인트 | 방법 | 설명 | -| -------------------------------- | ------ | -------------- | -| `/api/oauth/[provider]/[action]` | 다양한 | 공급자별 OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### 라우팅 및 구성 +### Routing & Config -| 엔드포인트 | 방법 | 설명 | -| --------------------- | --------- | ------------------------- | -| `/api/models/alias` | 받기/게시 | 모델 별칭 | -| `/api/models/catalog` | 받기 | 공급자 + 유형별 모든 모델 | -| `/api/combos*` | 다양한 | 콤보 관리 | -| `/api/keys*` | 다양한 | API 키 관리 | -| `/api/pricing` | 받기 | 모델 가격 | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### 사용 및 분석 +### Usage & Analytics -| 엔드포인트 | 방법 | 설명 | -| --------------------------- | ---- | -------------- | -| `/api/usage/history` | 받기 | 이용내역 | -| `/api/usage/logs` | 받기 | 사용 로그 | -| `/api/usage/request-logs` | 받기 | 요청 수준 로그 | -| `/api/usage/[connectionId]` | 받기 | 연결별 사용량 | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### 설정 +### Settings -| 엔드포인트 | 방법 | 설명 | -| ------------------------------- | ------------- | ---------------------- | -| `/api/settings` | 가져오기/넣기 | 일반 설정 | -| `/api/settings/proxy` | 가져오기/넣기 | 네트워크 프록시 구성 | -| `/api/settings/proxy/test` | 포스트 | 프록시 연결 테스트 | -| `/api/settings/ip-filter` | 가져오기/넣기 | IP 허용 목록/차단 목록 | -| `/api/settings/thinking-budget` | 가져오기/넣기 | 토큰 예산 추론 | -| `/api/settings/system-prompt` | 가져오기/넣기 | 글로벌 시스템 프롬프트 | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### 모니터링 +### Monitoring -| 엔드포인트 | 방법 | 설명 | -| ------------------------ | ------------- | ------------------ | -| `/api/sessions` | 받기 | 활성 세션 추적 | -| `/api/rate-limits` | 받기 | 계정당 비율 제한 | -| `/api/monitoring/health` | 받기 | 건강검진 | -| `/api/cache` | 가져오기/삭제 | 캐시 통계 / 지우기 | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### 백업 및 내보내기/가져오기 +### Backup & Export/Import -| 엔드포인트 | 방법 | 설명 | -| --------------------------- | ------ | ----------------------------------------- | -| `/api/db-backups` | 받기 | 사용 가능한 백업 나열 | -| `/api/db-backups` | 넣어 | 수동 백업 생성 | -| `/api/db-backups` | 포스트 | 특정 백업에서 복원 | -| `/api/db-backups/export` | 받기 | 데이터베이스를 .sqlite 파일로 다운로드 | -| `/api/db-backups/import` | 포스트 | 데이터베이스를 대체할 .sqlite 파일 업로드 | -| `/api/db-backups/exportAll` | 받기 | 전체 백업을 .tar.gz 아카이브로 다운로드 | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### 클라우드 동기화 +### Cloud Sync -| 엔드포인트 | 방법 | 설명 | -| ---------------------- | ------ | -------------------- | -| `/api/sync/cloud` | 다양한 | 클라우드 동기화 작업 | -| `/api/sync/initialize` | 포스트 | 동기화 초기화 | -| `/api/cloud/*` | 다양한 | 클라우드 관리 | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI 도구 +### CLI Tools -| 엔드포인트 | 방법 | 설명 | -| ---------------------------------- | ---- | ----------------- | -| `/api/cli-tools/claude-settings` | 받기 | 클로드 CLI 상태 | -| `/api/cli-tools/codex-settings` | 받기 | 코덱스 CLI 상태 | -| `/api/cli-tools/droid-settings` | 받기 | 드로이드 CLI 상태 | -| `/api/cli-tools/openclaw-settings` | 받기 | OpenClaw CLI 상태 | -| `/api/cli-tools/runtime/[toolId]` | 받기 | 일반 CLI 런타임 | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -CLI 응답에는 `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`이 포함됩니다. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### 복원력 및 속도 제한 +### ACP Agents -| 엔드포인트 | 방법 | 설명 | -| ----------------------- | ------------- | ------------------------------- | -| `/api/resilience` | 가져오기/넣기 | 탄력성 프로필 가져오기/업데이트 | -| `/api/resilience/reset` | 포스트 | 회로 차단기 재설정 | -| `/api/rate-limits` | 받기 | 계정별 비율한도 현황 | -| `/api/rate-limit` | 받기 | 글로벌 비율 제한 구성 | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### 평가 +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| 엔드포인트 | 방법 | 설명 | -| ------------ | --------- | -------------------------- | -| `/api/evals` | 받기/게시 | 평가 제품군 나열/평가 실행 | +### Resilience & Rate Limits -### 정책 +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| 엔드포인트 | 방법 | 설명 | -| --------------- | ------------------ | ---------------- | -| `/api/policies` | 가져오기/게시/삭제 | 라우팅 정책 관리 | +### Evals -### 규정 준수 +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| 엔드포인트 | 방법 | 설명 | -| --------------------------- | ---- | ----------------------------- | -| `/api/compliance/audit-log` | 받기 | 규정 준수 감사 로그(마지막 N) | +### Policies -### v1beta(Gemini 호환) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| 엔드포인트 | 방법 | 설명 | -| -------------------------- | ------ | --------------------------------------- | -| `/v1beta/models` | 받기 | Gemini 형식으로 모델 나열 | -| `/v1beta/models/{...path}` | 포스트 | 쌍둥이자리 `generateContent` 엔드포인트 | +### Compliance -이러한 엔드포인트는 기본 Gemini SDK 호환성을 기대하는 클라이언트를 위한 Gemini의 API 형식을 미러링합니다. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### 내부/시스템 API +### v1beta (Gemini-Compatible) -| 엔드포인트 | 방법 | 설명 | -| --------------- | ------ | ----------------------------------------- | -| `/api/init` | 받기 | 애플리케이션 초기화 확인(첫 실행 시 사용) | -| `/api/tags` | 받기 | Ollama 호환 모델 태그(Ollama 고객용) | -| `/api/restart` | 포스트 | 정상적인 서버 다시 시작 트리거 | -| `/api/shutdown` | 포스트 | 정상적인 서버 종료 트리거 | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **참고:** 이러한 끝점은 시스템 내부적으로 또는 Ollama 클라이언트 호환성을 위해 사용됩니다. 일반적으로 최종 사용자는 호출하지 않습니다. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## 오디오 전사 +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Deepgram 또는 AssemblyAI를 사용하여 오디오 파일을 녹음합니다. +Transcribe audio files using Deepgram or AssemblyAI. -**요청:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**응답:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**지원되는 제공업체:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**지원되는 형식:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## 올라마 호환성 +## Ollama Compatibility -Ollama의 API 형식을 사용하는 클라이언트의 경우: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -요청은 Ollama와 내부 형식 간에 자동으로 번역됩니다. +Requests are automatically translated between Ollama and internal formats. --- -## 원격 측정 +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**응답:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## 예산 +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## 모델 가용성 +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## 요청 처리 +## Request Processing -1. 클라이언트는 `/v1/*`에 요청을 보냅니다. -2. 경로 핸들러 호출 `handleChat`, `handleEmbedding`, `handleAudioTranscription` 또는 `handleImageGeneration` -3. 모델이 해결되었습니다(직접 공급자/모델 또는 별칭/콤보). -4. 계정 가용성 필터링을 통해 로컬 DB에서 자격 증명을 선택합니다. -5. 채팅의 경우: `handleChatCore` — 형식 감지, 번역, 캐시 확인, 멱등성 확인 -6. 공급자 실행자가 업스트림 요청을 보냅니다. -7. 응답은 클라이언트 형식(채팅)으로 다시 변환되거나 있는 그대로 반환됩니다(임베딩/이미지/오디오). -8. 사용/로깅 기록 -9. 콤보 규칙에 따라 오류 발생 시 Fallback 적용 +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -전체 아키텍처 참조: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## 인증 +## Authentication -- 대시보드 경로(`/dashboard/*`)는 `auth_token` 쿠키를 사용합니다. -- 로그인은 저장된 비밀번호 해시를 사용합니다. `INITIAL_PASSWORD`로 대체 -- `requireLogin`은 `/api/settings/require-login`을 통해 전환 가능 -- `/v1/*` 경로에는 `REQUIRE_API_KEY=true`인 경우 선택적으로 Bearer API 키가 필요합니다. +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/ko/ARCHITECTURE.md b/docs/i18n/ko/ARCHITECTURE.md index c8b2fffae9..258d62df53 100644 --- a/docs/i18n/ko/ARCHITECTURE.md +++ b/docs/i18n/ko/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# 옴니루트 아키텍처 +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_최종 업데이트 날짜: 2026-02-18_ +_Last updated: 2026-03-04_ -## 요약 +## Executive Summary -OmniRoute는 Next.js를 기반으로 구축된 로컬 AI 라우팅 게이트웨이이자 대시보드입니다. -단일 OpenAI 호환 엔드포인트(`/v1/*`)를 제공하고 변환, 대체, 토큰 새로 고침 및 사용 추적을 통해 여러 업스트림 공급자 간에 트래픽을 라우팅합니다. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -핵심 기능: +Core capabilities: -- CLI/도구용 OpenAI 호환 API 표면(28개 공급자) -- 공급자 형식에 따른 요청/응답 번역 -- 모델 콤보 대체(다중 모델 시퀀스) -- 계정 수준 대체(제공업체당 다중 계정) -- OAuth + API 키 공급자 연결 관리 -- `/v1/embeddings`을 통한 임베딩 생성(6개 공급자, 9개 모델) -- `/v1/images/generations`을 통한 이미지 생성(4개 공급자, 9개 모델) -- 추론 모델을 위한 Think 태그 구문 분석(`...`) -- 엄격한 OpenAI SDK 호환성을 위한 응답 삭제 -- 제공자 간 호환성을 위한 역할 정규화(개발자→시스템, 시스템→사용자) -- 구조화된 출력 변환(json_schema → Gemini responseSchema) -- 공급자, 키, 별칭, 콤보, 설정, 가격에 대한 로컬 지속성 -- 사용량/비용 추적 및 요청 로깅 -- 다중 장치/상태 동기화를 위한 선택적 클라우드 동기화 -- API 접근 제어를 위한 IP 허용 목록/차단 목록 -- 생각하는 예산 관리(패스스루/자동/커스텀/적응형) -- 글로벌 시스템 신속한 주입 -- 세션 추적 및 지문 채취 -- 제공자별 프로필을 통해 계정당 강화된 속도 제한 -- 공급자 탄력성을 위한 회로 차단기 패턴 -- 뮤텍스 잠금을 통한 천둥 방지 무리 보호 -- 서명 기반 요청 중복 제거 캐시 -- 도메인 레이어: 모델 가용성, 비용 규칙, 대체 정책, 잠금 정책 -- 도메인 상태 지속성(폴백, 예산, 잠금, 회로 차단기를 위한 SQLite 연속 쓰기 캐시) -- 중앙화된 요청 평가를 위한 정책 엔진(잠금 → 예산 → 대체) -- p50/p95/p99 대기 시간 집계를 통한 원격 측정 요청 -- 종단 간 추적을 위한 상관 ID(X-Request-Id) -- API 키별로 옵트아웃이 가능한 규정 준수 감사 로깅 -- LLM 품질 보증을 위한 평가 프레임워크 -- 실시간 회로 차단기 상태가 포함된 탄력성 UI 대시보드 -- 모듈식 OAuth 제공자(`src/lib/oauth/providers/` 아래의 개별 모듈 12개) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -기본 런타임 모델: +Primary runtime model: -- `src/app/api/*` 아래의 Next.js 앱 경로는 대시보드 API와 호환성 API를 모두 구현합니다. -- `src/sse/*` + `open-sse/*`의 공유 SSE/라우팅 코어는 공급자 실행, 변환, 스트리밍, 대체 및 사용을 처리합니다. +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## 범위 및 경계 +## Scope and Boundaries -### 범위 내 +### In Scope -- 로컬 게이트웨이 런타임 -- 대시보드 관리 API -- 공급자 인증 및 토큰 새로 고침 -- 번역 및 SSE 스트리밍 요청 -- 로컬 상태 + 사용 지속성 -- 선택적인 클라우드 동기화 조정 +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### 범위를 벗어남 +### Out of Scope -- `NEXT_PUBLIC_CLOUD_URL` 기반의 클라우드 서비스 구현 -- 로컬 프로세스 외부의 공급자 SLA/제어 평면 -- 외부 CLI 바이너리 자체(Claude CLI, Codex CLI 등) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## 상위 수준 시스템 컨텍스트 +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## 핵심 런타임 구성 요소 +## Core Runtime Components -## 1) API 및 라우팅 계층(Next.js 앱 경로) +## 1) API and Routing Layer (Next.js App Routes) -주요 디렉토리: +Main directories: -- 호환성 API의 경우 `src/app/api/v1/*` 및 `src/app/api/v1beta/*` -- 관리/구성 API용 `src/app/api/*` -- 다음은 `next.config.mjs`에서 `/v1/*`을 `/api/v1/*`로 매핑하여 다시 작성합니다. +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -중요한 호환성 경로: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — `custom: true`이 있는 사용자 정의 모델을 포함합니다. -- `src/app/api/v1/embeddings/route.ts` — 임베딩 생성(6개 제공자) -- `src/app/api/v1/images/generations/route.ts` — 이미지 생성(Antigravity/Nebius를 포함한 4개 이상의 공급자) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — 제공업체별 전용 채팅 -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — 제공자별 전용 임베딩 -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — 제공업체별 전용 이미지 +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -관리 도메인: +Management domains: -- 인증/설정: `src/app/api/auth/*`, `src/app/api/settings/*` -- 공급자/연결: `src/app/api/providers*` -- 제공자 노드: `src/app/api/provider-nodes*` -- 사용자 정의 모델: `src/app/api/provider-models` (GET/POST/DELETE) -- 모델 카탈로그: `src/app/api/models/catalog` (GET) -- 프록시 구성: `src/app/api/settings/proxy`(GET/PUT/DELETE) + `src/app/api/settings/proxy/test`(POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- 키/별칭/콤보/가격: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- 사용량: `src/app/api/usage/*` -- 동기화/클라우드: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI 도구 도우미: `src/app/api/cli-tools/*` -- IP 필터: `src/app/api/settings/ip-filter` (GET/PUT) -- 생각하는 예산: `src/app/api/settings/thinking-budget` (GET/PUT) -- 시스템 프롬프트: `src/app/api/settings/system-prompt` (GET/PUT) -- 세션: `src/app/api/sessions`(GET) -- 비율 제한: `src/app/api/rate-limits` (GET) -- 복원력: `src/app/api/resilience` (GET/PATCH) — 공급자 프로필, 회로 차단기, 속도 제한 상태 -- 복원력 재설정: `src/app/api/resilience/reset` (POST) — 차단기 재설정 + 재사용 대기시간 -- 캐시 통계: `src/app/api/cache/stats` (GET/DELETE) -- 모델 가용성: `src/app/api/models/availability` (GET/POST) -- 원격 측정: `src/app/api/telemetry/summary` (GET) -- 예산: `src/app/api/usage/budget` (GET/POST) -- 대체 체인: `src/app/api/fallback/chains` (GET/POST/DELETE) -- 규정 준수 감사: `src/app/api/compliance/audit-log` (GET) -- 평가: `src/app/api/evals`(GET/POST), `src/app/api/evals/[suiteId]`(GET) -- 정책: `src/app/api/policies`(GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + 번역 코어 +## 2) SSE + Translation Core -주요 흐름 모듈: +Main flow modules: -- 항목: `src/sse/handlers/chat.ts` -- 핵심 오케스트레이션: `open-sse/handlers/chatCore.ts` -- 공급자 실행 어댑터: `open-sse/executors/*` -- 형식 감지/공급자 구성: `open-sse/services/provider.ts` -- 모델 구문 분석/해결: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- 계정 대체 논리: `open-sse/services/accountFallback.ts` -- 번역 레지스트리: `open-sse/translator/index.ts` -- 스트림 변환: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- 사용량 추출/정규화: `open-sse/utils/usageTracking.ts` -- 태그 파서 생각: `open-sse/utils/thinkTagParser.ts` -- 임베딩 핸들러: `open-sse/handlers/embeddings.ts` -- 임베딩 제공자 레지스트리: `open-sse/config/embeddingRegistry.ts` -- 이미지 생성 핸들러: `open-sse/handlers/imageGeneration.ts` -- 이미지 제공자 레지스트리: `open-sse/config/imageRegistry.ts` -- 응답 정리: `open-sse/handlers/responseSanitizer.ts` -- 역할 정규화: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -서비스(비즈니스 로직): +Services (business logic): -- 계정 선택/점수: `open-sse/services/accountSelector.ts` -- 컨텍스트 수명주기 관리: `open-sse/services/contextManager.ts` -- IP 필터 시행: `open-sse/services/ipFilter.ts` -- 세션 추적: `open-sse/services/sessionManager.ts` -- 중복 제거 요청: `open-sse/services/signatureCache.ts` -- 시스템 프롬프트 주입: `open-sse/services/systemPrompt.ts` -- 생각하는 예산 관리: `open-sse/services/thinkingBudget.ts` -- 와일드카드 모델 라우팅: `open-sse/services/wildcardRouter.ts` -- 비율 제한 관리: `open-sse/services/rateLimitManager.ts` -- 회로 차단기: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -도메인 레이어 모듈: +Domain layer modules: -- 모델 가용성: `src/lib/domain/modelAvailability.ts` -- 비용 규칙/예산: `src/lib/domain/costRules.ts` -- 대체 정책: `src/lib/domain/fallbackPolicy.ts` -- 콤보 리졸버: `src/lib/domain/comboResolver.ts` -- 잠금 정책: `src/lib/domain/lockoutPolicy.ts` -- 정책 엔진: `src/domain/policyEngine.ts` — 중앙 집중식 잠금 → 예산 → 대체 평가 -- 오류 코드 카탈로그: `src/lib/domain/errorCodes.ts` -- 요청 ID: `src/lib/domain/requestId.ts` -- 가져오기 시간 초과: `src/lib/domain/fetchTimeout.ts` -- 원격 측정 요청: `src/lib/domain/requestTelemetry.ts` -- 규정 준수/감사: `src/lib/domain/compliance/index.ts` -- 평가 실행자: `src/lib/domain/evalRunner.ts` -- 도메인 상태 지속성: `src/lib/db/domainState.ts` — 대체 체인, 예산, 비용 기록, 잠금 상태, 회로 차단기를 위한 SQLite CRUD +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth 제공자 모듈(`src/lib/oauth/providers/` 아래의 개별 파일 12개): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- 레지스트리 색인: `src/lib/oauth/providers/index.ts` -- 개인 공급자: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- 씬 래퍼: `src/lib/oauth/providers.ts` — 개별 모듈에서 다시 내보내기 +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) 지속성 레이어 +## 3) Persistence Layer -기본 상태 DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- 파일: `${DATA_DIR}/db.json`(또는 설정된 경우 `$XDG_CONFIG_HOME/omniroute/db.json`, 그렇지 않으면 `~/.omniroute/db.json`) -- 엔터티: 공급자 연결, 공급자 노드, modelAliases, 콤보, apiKeys, 설정, 가격 책정, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -사용량 DB: +Usage persistence: -- `src/lib/usageDb.ts` -- 파일: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- `localDb`(`DATA_DIR`, 설정된 경우 `XDG_CONFIG_HOME/omniroute`)과 동일한 기본 디렉터리 정책을 따릅니다. -- 집중된 하위 모듈로 분해: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -도메인 상태 DB(SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — 도메인 상태에 대한 CRUD 작업 -- 테이블(`src/lib/db/core.ts`에서 생성됨): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- 연속 쓰기 캐시 패턴: 메모리 내 맵은 런타임 시 권한을 갖습니다. 변이는 SQLite에 동기적으로 기록됩니다. 콜드 스타트 시 DB에서 상태가 복원됩니다. +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) 인증 + 보안 표면 +## 4) Auth + Security Surfaces -- 대시보드 쿠키 인증: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- API 키 생성/검증: `src/shared/utils/apiKey.ts` -- `providerConnections` 항목에 유지되는 공급자 비밀 -- `open-sse/utils/proxyFetch.ts`(env vars) 및 `open-sse/utils/networkProxy.ts`(공급자별 또는 전역 구성 가능)을 통한 아웃바운드 프록시 지원 +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) 클라우드 동기화 +## 5) Cloud Sync -- 스케줄러 초기화: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- 정기 작업: `src/shared/services/cloudSyncScheduler.ts` -- 제어 경로: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## 요청 수명 주기(`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## 콤보 + 계정 대체 흐름 +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -대체 결정은 상태 코드와 오류 메시지 휴리스틱을 사용하는 `open-sse/services/accountFallback.ts`에 의해 이루어집니다. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth 온보딩 및 토큰 새로 고침 수명 주기 +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -실시간 트래픽 중 새로 고침은 실행기 `refreshCredentials()`을 통해 `open-sse/handlers/chatCore.ts` 내에서 실행됩니다. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## 클라우드 동기화 수명 주기(활성화/동기화/비활성화) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -클라우드가 활성화되면 `CloudSyncScheduler`에 의해 주기적 동기화가 트리거됩니다. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## 데이터 모델 및 스토리지 맵 +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -물리적 저장 파일: +Physical storage files: -- 기본 상태: `${DATA_DIR}/db.json`(또는 설정된 경우 `$XDG_CONFIG_HOME/omniroute/db.json`, 그렇지 않으면 `~/.omniroute/db.json`) -- 사용 통계: `${DATA_DIR}/usage.json` -- 요청 로그 라인: `${DATA_DIR}/log.txt` -- 선택적 변환기/요청 디버그 세션: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## 배포 토폴로지 +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## 모듈 매핑(결정에 중요) +## Module Mapping (Decision-Critical) -### 경로 및 API 모듈 +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: 호환성 API -- `src/app/api/v1/providers/[provider]/*`: 공급자별 전용 경로(채팅, 임베딩, 이미지) -- `src/app/api/providers*`: 공급자 CRUD, 유효성 검사, 테스트 -- `src/app/api/provider-nodes*`: 맞춤형 호환 노드 관리 -- `src/app/api/provider-models`: 사용자 정의 모델 관리(CRUD) -- `src/app/api/models/catalog`: 전체 모델 카탈로그 API(모든 유형이 공급자별로 그룹화됨) -- `src/app/api/oauth/*`: OAuth/장치 코드 흐름 -- `src/app/api/keys*`: 로컬 API 키 수명 주기 -- `src/app/api/models/alias`: 별칭 관리 -- `src/app/api/combos*`: 대체 콤보 관리 -- `src/app/api/pricing`: 비용 계산을 위한 가격 재정의 -- `src/app/api/settings/proxy`: 프록시 구성(GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: 아웃바운드 프록시 연결 테스트(POST) -- `src/app/api/usage/*`: 사용량 및 로그 API -- `src/app/api/sync/*` + `src/app/api/cloud/*`: 클라우드 동기화 및 클라우드 연결 도우미 -- `src/app/api/cli-tools/*`: 로컬 CLI 구성 작성자/검사기 -- `src/app/api/settings/ip-filter`: IP 허용 목록/차단 목록(GET/PUT) -- `src/app/api/settings/thinking-budget`: 생각하는 토큰 예산 구성(GET/PUT) -- `src/app/api/settings/system-prompt`: 전역 시스템 프롬프트(GET/PUT) -- `src/app/api/sessions`: 활성 세션 목록(GET) -- `src/app/api/rate-limits`: 계정별 비율 제한 상태(GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### 라우팅 및 실행 코어 +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: 요청 구문 분석, 콤보 처리, 계정 선택 루프 -- `open-sse/handlers/chatCore.ts`: 변환, 실행기 디스패치, 재시도/새로 고침 처리, 스트림 설정 -- `open-sse/executors/*`: 공급자별 네트워크 및 형식 동작 +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### 번역 레지스트리 및 형식 변환기 +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: 번역자 레지스트리 및 오케스트레이션 -- 번역자 요청: `open-sse/translator/request/*` -- 응답 번역자: `open-sse/translator/response/*` -- 형식 상수: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### 지속성 +### Persistence -- `src/lib/localDb.ts`: 영구 구성/상태 -- `src/lib/usageDb.ts`: 사용 내역 및 롤링 요청 로그 +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## 제공자 실행자 적용 범위(전략 패턴) +## Provider Executor Coverage (Strategy Pattern) -각 공급자에는 URL 구축, 헤더 구성, 지수 백오프를 사용한 재시도, 자격 증명 새로 고침 후크 및 `execute()` 오케스트레이션 방법을 제공하는 `BaseExecutor`(`open-sse/executors/base.ts`)을 확장하는 특수 실행기가 있습니다. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| 집행자 | 공급자 | 특수취급 | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | 공급자별 동적 URL/헤더 구성 | -| `AntigravityExecutor` | 구글 반중력 | 사용자 정의 프로젝트/세션 ID, 구문 분석 후 재시도 | -| `CodexExecutor` | OpenAI 코덱스 | 시스템 지침을 주입하고 추론 노력을 강요 | -| `CursorExecutor` | 커서 IDE | ConnectRPC 프로토콜, Protobuf 인코딩, 체크섬을 통한 서명 요청 | -| `GithubExecutor` | GitHub 부조종사 | Copilot 토큰 새로 고침, VSCode 모방 헤더 | -| `KiroExecutor` | AWS 코드위스퍼러/키로 | AWS EventStream 바이너리 형식 → SSE 변환 | -| `GeminiCLIExecutor` | 제미니 CLI | Google OAuth 토큰 새로고침 주기 | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -다른 모든 공급자(사용자 정의 호환 노드 포함)는 `DefaultExecutor`을 사용합니다. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## 공급자 호환성 매트릭스 +## Provider Compatibility Matrix -| 공급자 | 형식 | 인증 | 스트림 | 비스트림 | 토큰 새로고침 | 사용 API | -| ----------------- | -------------- | -------------------- | ----------------- | -------- | ------------- | ------------------ | -| 클로드 | 클로드 | API 키/OAuth | ✅ | ✅ | ✅ | ⚠️ 관리자 전용 | -| 쌍둥이자리 | 쌍둥이자리 | API 키/OAuth | ✅ | ✅ | ✅ | ⚠️ 클라우드 콘솔 | -| 제미니 CLI | 쌍둥이자리 CLI | OAuth | ✅ | ✅ | ✅ | ⚠️ 클라우드 콘솔 | -| 반중력 | 반중력 | OAuth | ✅ | ✅ | ✅ | ✅ 전체 할당량 API | -| 오픈AI | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 코덱스 | openai-응답 | OAuth | ✅ 강제 | ❌ | ✅ | ✅ 비율 제한 | -| GitHub 부조종사 | 공개 | OAuth + Copilot 토큰 | ✅ | ✅ | ✅ | ✅ 할당량 스냅샷 | -| 커서 | 커서 | 사용자 정의 체크섬 | ✅ | ✅ | ❌ | ❌ | -| 키로 | 키로 | AWS SSO OIDC | ✅ (이벤트스트림) | ❌ | ✅ | ✅ 사용 제한 | -| 퀀 | 공개 | OAuth | ✅ | ✅ | ✅ | ⚠️ 요청에 따라 | -| 아이플로우 | 공개 | OAuth(기본) | ✅ | ✅ | ✅ | ⚠️ 요청에 따라 | -| 오픈라우터 | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| GLM/키미/미니맥스 | 클로드 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 딥시크 | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 그로크 | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| xAI(그록) | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 미스트랄 | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 당혹감 | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 함께하는 AI | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 불꽃놀이 AI | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 대뇌 | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 코히어 | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | -| 엔비디아 NIM | 공개 | API 키 | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## 형식 번역 범위 +## Format Translation Coverage -감지된 소스 형식은 다음과 같습니다. +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -대상 형식은 다음과 같습니다. +Target formats include: -- OpenAI 채팅/응답 -- 클로드 -- Gemini/Gemini-CLI/반중력 봉투 -- 키로 -- 커서 +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -번역에서는 **OpenAI를 허브 형식**으로 사용합니다. 모든 변환은 중간 형식으로 OpenAI를 거칩니다. +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -번역은 소스 페이로드 형태와 공급자 대상 형식에 따라 동적으로 선택됩니다. +Translations are selected dynamically based on source payload shape and provider target format. -번역 파이프라인의 추가 처리 계층: +Additional processing layers in the translation pipeline: -- **응답 삭제** — OpenAI 형식 응답(스트리밍 및 비스트리밍 모두)에서 비표준 필드를 제거하여 엄격한 SDK 규정 준수를 보장합니다. -- **역할 정규화** — OpenAI가 아닌 대상에 대해 `developer` → `system`을 변환합니다. 시스템 역할(GLM, ERNIE)을 거부하는 모델에 대해 `system` → `user`을 병합합니다. -- **태그 추출 생각** — 콘텐츠의 `...` 블록을 `reasoning_content` 필드로 구문 분석합니다. -- **구조화된 출력** — OpenAI `response_format.json_schema`을 Gemini의 `responseMimeType` + `responseSchema`로 변환합니다. +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## 지원되는 API 엔드포인트 +## Supported API Endpoints -| 엔드포인트 | 형식 | 핸들러 | -| -------------------------------------------------- | ------------------ | --------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI 채팅 | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | 클로드 메시지 | 동일한 핸들러(자동 감지) | -| `POST /v1/responses` | OpenAI 응답 | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI 임베딩 | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | 모델 목록 | API 경로 | -| `POST /v1/images/generations` | OpenAI 이미지 | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | 모델 목록 | API 경로 | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI 채팅 | 모델 검증을 통한 제공자별 전용 | -| `POST /v1/providers/{provider}/embeddings` | OpenAI 임베딩 | 모델 검증을 통한 제공자별 전용 | -| `POST /v1/providers/{provider}/images/generations` | OpenAI 이미지 | 모델 검증을 통한 제공자별 전용 | -| `POST /v1/messages/count_tokens` | 클로드 토큰 개수 | API 경로 | -| `GET /v1/models` | OpenAI 모델 목록 | API 경로(채팅 + 임베딩 + 이미지 + 사용자 정의 모델) | -| `GET /api/models/catalog` | 카탈로그 | 공급자 + 유형별로 그룹화된 모든 모델 | -| `POST /v1beta/models/*:streamGenerateContent` | 쌍둥이 자리 원주민 | API 경로 | -| `GET/PUT/DELETE /api/settings/proxy` | 프록시 구성 | 네트워크 프록시 구성 | -| `POST /api/settings/proxy/test` | 프록시 연결 | 프록시 상태/연결 테스트 엔드포인트 | -| `GET/POST/DELETE /api/provider-models` | 맞춤형 모델 | 제공자별 맞춤형 모델 관리 | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## 우회 핸들러 +## Bypass Handler -우회 처리기(`open-sse/utils/bypassHandler.ts`)는 Claude CLI의 알려진 "일시적" 요청(예열 핑, 타이틀 추출 및 토큰 계산)을 가로채고 업스트림 공급자 토큰을 사용하지 않고 **가짜 응답**을 반환합니다. 이는 `User-Agent`에 `claude-cli`이 포함된 경우에만 트리거됩니다. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## 요청 로거 파이프라인 +## Request Logger Pipeline -요청 로거(`open-sse/utils/requestLogger.ts`)는 기본적으로 비활성화되고 `ENABLE_REQUEST_LOGS=true`을 통해 활성화되는 7단계 디버그 로깅 파이프라인을 제공합니다. +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -각 요청 세션마다 파일이 `/logs//`에 기록됩니다. +Files are written to `/logs//` for each request session. -## 실패 모드 및 복원력 +## Failure Modes and Resilience -## 1) 계정/공급업체 가용성 +## 1) Account/Provider Availability -- 일시적/속도/인증 오류에 대한 공급자 계정 쿨다운 -- 요청 실패 전 계정 대체 -- 현재 모델/공급자 경로가 소진되면 콤보 모델 대체 +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) 토큰 만료 +## 2) Token Expiry -- 새로 고칠 수 있는 공급자에 대한 사전 확인 및 재시도를 통한 새로 고침 -- 코어 경로에서 새로 고침 시도 후 401/403 재시도 +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) 스트림 안전 +## 3) Stream Safety -- 연결 해제 인식 스트림 컨트롤러 -- 스트림 끝 플러시 및 `[DONE]` 처리가 포함된 번역 스트림 -- 공급자 사용량 메타데이터가 누락된 경우 사용량 추정 대체 +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) 클라우드 동기화 성능 저하 +## 4) Cloud Sync Degradation -- 동기화 오류가 표시되지만 로컬 런타임은 계속됩니다. -- 스케줄러에는 재시도 가능 논리가 있지만 주기적인 실행은 현재 기본적으로 단일 시도 동기화를 호출합니다. +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) 데이터 무결성 +## 5) Data Integrity -- 누락된 키에 대한 DB 형상 마이그레이션/수정 -- localDb 및 UsageDb에 대한 손상된 JSON 재설정 보호 장치 +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## 관찰 가능성 및 작동 신호 +## Observability and Operational Signals -런타임 가시성 소스: +Runtime visibility sources: -- `src/sse/utils/logger.ts`의 콘솔 로그 -- `usage.json`의 요청별 사용량 집계 -- `log.txt`의 텍스트 요청 상태 로그 -- `ENABLE_REQUEST_LOGS=true`인 경우 `logs/` 아래의 선택적 심층 요청/번역 로그 -- UI 소비를 위한 대시보드 사용 끝점(`/api/usage/*`) +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## 보안에 민감한 경계 +## Security-Sensitive Boundaries -- JWT 비밀(`JWT_SECRET`)은 대시보드 세션 쿠키 확인/서명을 보호합니다. -- 실제 배포에서는 초기 비밀번호 대체(`INITIAL_PASSWORD`, 기본값 `123456`)를 재정의해야 합니다. -- API 키 HMAC 비밀(`API_KEY_SECRET`)은 생성된 로컬 API 키 형식을 보호합니다. -- 공급자 비밀(API 키/토큰)은 로컬 DB에 유지되며 파일 시스템 수준에서 보호되어야 합니다. -- 클라우드 동기화 엔드포인트는 API 키 인증 + 머신 ID 의미 체계를 사용합니다. +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## 환경 및 런타임 매트릭스 +## Environment and Runtime Matrix -코드에서 적극적으로 사용되는 환경 변수: +Environment variables actively used by code: -- 앱/인증: `JWT_SECRET`, `INITIAL_PASSWORD` -- 저장공간: `DATA_DIR` -- 호환 노드 동작: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- 선택적 저장소 기반 재정의(`DATA_DIR`이 설정되지 않은 경우 Linux/macOS): `XDG_CONFIG_HOME` -- 보안 해싱: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- 로깅: `ENABLE_REQUEST_LOGS` -- 동기화/클라우드 URL링: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- 아웃바운드 프록시: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` 및 소문자 변형 -- SOCKS5 기능 플래그: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- 플랫폼/런타임 도우미(앱별 구성 아님): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## 알려진 아키텍처 노트 +## Known Architectural Notes -1. `usageDb` 및 `localDb`은 이제 레거시 파일 마이그레이션과 동일한 기본 디렉터리 정책(`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`)을 공유합니다. -2. `/api/v1/route.ts`은 정적 모델 목록을 반환하며 `/v1/models`에서 사용하는 기본 모델 소스가 아닙니다. -3. 요청 로거가 활성화되면 전체 헤더/본문을 씁니다. 로그 디렉토리를 중요하게 취급하십시오. -4. 클라우드 동작은 올바른 `NEXT_PUBLIC_BASE_URL` 및 클라우드 엔드포인트 연결 가능성에 따라 달라집니다. -5. `open-sse/` 디렉터리는 `@omniroute/open-sse` **npm 작업 공간 패키지**로 게시됩니다. 소스 코드는 `@omniroute/open-sse/...`을 통해 이를 가져옵니다(Next.js `transpilePackages`으로 해결됨). 이 문서의 파일 경로는 일관성을 위해 여전히 디렉터리 이름 `open-sse/`을 사용합니다. -6. 대시보드의 차트는 액세스 가능한 대화형 분석 시각화(모델 사용량 막대 차트, 성공률이 포함된 공급자 분석 테이블)를 위해 **Recharts**(SVG 기반)를 사용합니다. -7. E2E 테스트는 **Playwright**(`tests/e2e/`)를 사용하고 `npm run test:e2e`을 통해 실행됩니다. 단위 테스트는 **Node.js 테스트 실행기**(`tests/unit/`)를 사용하고 `npm run test:plan3`을 통해 실행됩니다. `src/` 아래의 소스 코드는 **TypeScript**(`.ts`/`.tsx`)입니다. `open-sse/` 작업 공간은 JavaScript(`.js`)로 유지됩니다. -8. 설정 페이지는 보안, 라우팅(6개의 전역 전략: 채우기 우선, 라운드 로빈, p2c, 무작위, 최소 사용, 비용 최적화), 탄력성(편집 가능한 속도 제한, 회로 차단기, 정책), AI(생각 예산, 시스템 프롬프트, 프롬프트 캐시), 고급(프록시)의 5개 탭으로 구성됩니다. +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## 작동 검증 체크리스트 +## Operational Verification Checklist -- 소스에서 빌드: `npm run build` -- Docker 이미지 빌드: `docker build -t omniroute .` -- 서비스 시작 및 확인: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- `PORT=20128`인 경우 CLI 대상 기본 URL은 `http://:20128/v1`이어야 합니다. +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ko/CODEBASE_DOCUMENTATION.md b/docs/i18n/ko/CODEBASE_DOCUMENTATION.md index d4f98a1f70..303880c198 100644 --- a/docs/i18n/ko/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/ko/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — 코드베이스 문서 +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> **옴니루트** 다중 제공자 AI 프록시 라우터에 대한 포괄적이고 초보자 친화적인 가이드입니다. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. 옴니루트란? +## 1. What Is omniroute? -omniroute는 AI 클라이언트(Claude CLI, Codex, Cursor IDE 등)와 AI 공급자(Anthropic, Google, OpenAI, AWS, GitHub 등) 사이에 위치하는 **프록시 라우터**입니다. 이는 하나의 큰 문제를 해결합니다. +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **다양한 AI 클라이언트는 서로 다른 "언어"(API 형식)를 사용하며, 다양한 AI 제공업체도 서로 다른 "언어"를 기대합니다.** omniroute는 이들 사이를 자동으로 변환합니다. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -UN의 범용 통역사처럼 생각해보세요. 모든 대표는 모든 언어를 말할 수 있으며 번역자는 다른 대표를 위해 이를 변환합니다. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. 아키텍처 개요 +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### 핵심 원칙: 허브 앤 스포크 번역 +### Core Principle: Hub-and-Spoke Translation -모든 형식 번역은 **OpenAI 형식을 허브**로 통과합니다. +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -즉, **N²**(모든 쌍) 대신 **N 번역자**(형식당 하나)만 필요하다는 의미입니다. +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. 프로젝트 구조 +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. 모듈별 분석 +## 4. Module-by-Module Breakdown -### 4.1 구성(`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -모든 공급자 구성에 대한 **단일 정보 소스**. +The **single source of truth** for all provider configuration. -| 파일 | 목적 | -| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | 모든 공급자에 대한 기본 URL, OAuth 자격 증명(기본값), 헤더 및 기본 시스템 프롬프트가 포함된 `PROVIDERS` 개체입니다. 또한 `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` 및 `SKIP_PATTERNS`을 정의합니다. | -| `credentialLoader.ts` | `data/provider-credentials.json`에서 외부 자격 증명을 로드하고 `PROVIDERS`의 하드코딩된 기본값에 병합합니다. 이전 버전과의 호환성을 유지하면서 소스 제어에서 비밀을 유지합니다. | -| `providerModels.ts` | 중앙 모델 레지스트리: 공급자 별칭 → 모델 ID를 매핑합니다. `getModels()`, `getProviderByAlias()`과 같은 함수입니다. | -| `codexInstructions.ts` | Codex 요청에 주입된 시스템 지침(제약 조건, 샌드박스 규칙, 승인 정책 편집) | -| `defaultThinkingSignature.ts` | Claude 및 Gemini 모델의 기본 "사고" 서명입니다. | -| `ollamaModels.ts` | 로컬 Ollama 모델에 대한 스키마 정의(이름, 크기, 계열, 양자화) | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### 자격 증명 로드 흐름 +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 실행자(`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -실행자는 **전략 패턴**을 사용하여 **제공자별 로직**을 캡슐화합니다. 각 실행자는 필요에 따라 기본 메서드를 재정의합니다. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| 집행자 | 공급자 | 주요 전문 분야 | -| ---------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | 추상 기반: URL 구축, 헤더, 재시도 논리, 자격 증명 새로 고침 | -| `default.ts` | 클로드, 제미니, OpenAI, GLM, 키미, 미니맥스 | 표준 공급자를 위한 일반 OAuth 토큰 새로 고침 | -| `antigravity.ts` | Google 클라우드 코드 | 프로젝트/세션 ID 생성, 다중 URL 대체, 오류 메시지에서 사용자 정의 재시도 구문 분석("2시간 7분 23초 후 재설정") | -| `cursor.ts` | 커서 IDE | **가장 복잡함**: SHA-256 체크섬 인증, Protobuf 요청 인코딩, 바이너리 EventStream → SSE 응답 구문 분석 | -| `codex.ts` | OpenAI 코덱스 | 시스템 지침 주입, ​​사고 수준 관리, 지원되지 않는 매개변수 제거 | -| `gemini-cli.ts` | 구글 제미니 CLI | 맞춤 URL 구축(`streamGenerateContent`), Google OAuth 토큰 새로고침 | -| `github.ts` | GitHub 부조종사 | 듀얼 토큰 시스템(GitHub OAuth + Copilot 토큰), VSCode 헤더 모방 | -| `kiro.ts` | AWS 코드위스퍼러 | AWS EventStream 바이너리 구문 분석, AMZN 이벤트 프레임, 토큰 추정 | -| `index.ts` | — | 팩토리: 기본 폴백을 사용하여 공급자 이름 → 실행자 클래스 매핑 | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 핸들러(`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**조정 레이어** — 번역, 실행, 스트리밍 및 오류 처리를 조정합니다. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| 파일 | 목적 | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **중앙 오케스트레이터**(~600줄). 형식 감지 → 변환 → 실행기 디스패치 → 스트리밍/비스트리밍 응답 → 토큰 새로 고침 → 오류 처리 → 사용 로깅 등 전체 요청 수명 주기를 처리합니다. | -| `responsesHandler.ts` | OpenAI의 응답 API용 어댑터: 응답 형식 변환 → 채팅 완료 → `chatCore`로 전송 → SSE를 다시 응답 형식으로 변환합니다. | -| `embeddings.ts` | 임베딩 생성 핸들러: 임베딩 모델 → 공급자를 확인하고 공급자 API로 디스패치하고 OpenAI 호환 임베딩 응답을 반환합니다. 6개 이상의 공급자를 지원합니다. | -| `imageGeneration.ts` | 이미지 생성 핸들러: 이미지 모델 → 공급자를 확인하고 OpenAI 호환, Gemini 이미지(반중력) 및 폴백(Nebius) 모드를 지원합니다. base64 또는 URL 이미지를 반환합니다. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### 요청 수명 주기(chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 서비스 (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -처리기와 실행기를 지원하는 비즈니스 논리입니다. +Business logic that supports the handlers and executors. -| 파일 | 목적 | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **형식 감지**(`detectFormat`): 요청 본문 구조를 분석하여 Claude/OpenAI/Gemini/반중력/응답 형식을 식별합니다(Claude에 대한 `max_tokens` 휴리스틱 포함). 또한: URL 구축, 헤더 구축, 구성 정규화 사고. `openai-compatible-*` 및 `anthropic-compatible-*` 동적 공급자를 지원합니다. | -| `model.ts` | 모델 문자열 구문 분석(`claude/model-name` → `{provider: "claude", model: "model-name"}`), 충돌 감지를 통한 별칭 해결, 입력 삭제(경로 순회/제어 문자 거부), 비동기 별칭 getter 지원을 통한 모델 정보 확인. | -| `accountFallback.ts` | 속도 제한 처리: 지수 백오프(1초 → 2초 → 4초 → 최대 2분), 계정 휴지 관리, 오류 분류(오류가 대체를 트리거하는지 여부). | -| `tokenRefresh.ts` | **모든 공급자**에 대한 OAuth 토큰 새로 고침: Google(Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub(OAuth + Copilot 이중 토큰), Kiro(AWS SSO OIDC + Social Auth). 진행 중인 약속 중복 제거 캐시 및 지수 백오프를 통한 재시도가 포함됩니다. | -| `combo.ts` | **콤보 모델**: 대체 모델 체인입니다. 모델 A가 대체 가능 오류로 인해 실패하는 경우 모델 B를 시도한 다음 C를 시도합니다. 실제 업스트림 상태 코드를 반환합니다. | -| `usage.ts` | 공급자 API(GitHub Copilot 할당량, 반중력 모델 할당량, Codex 속도 제한, Kiro 사용량 분석, Claude 설정)에서 할당량/사용 데이터를 가져옵니다. | -| `accountSelector.ts` | 채점 알고리즘을 사용한 스마트 계정 선택: 우선순위, 상태, 라운드 로빈 위치 및 쿨다운 상태를 고려하여 각 요청에 대한 최적의 계정을 선택합니다. | -| `contextManager.ts` | 요청 컨텍스트 수명 주기 관리: 디버깅 및 로깅을 위한 메타데이터(요청 ID, 타임스탬프, 공급자 정보)가 포함된 요청별 컨텍스트 개체를 생성하고 추적합니다. | -| `ipFilter.ts` | IP 기반 액세스 제어: 허용 목록 및 차단 목록 모드를 지원합니다. API 요청을 처리하기 전에 구성된 규칙에 따라 클라이언트 IP를 검증합니다. | -| `sessionManager.ts` | 클라이언트 핑거프린팅을 통한 세션 추적: 해시된 클라이언트 식별자를 사용하여 활성 세션을 추적하고, 요청 수를 모니터링하고, 세션 메트릭을 제공합니다. | -| `signatureCache.ts` | 요청 서명 기반 중복 제거 캐시: 최근 요청 서명을 캐시하고 일정 기간 내에 동일한 요청에 대해 캐시된 응답을 반환하여 중복 요청을 방지합니다. | -| `systemPrompt.ts` | 글로벌 시스템 프롬프트 삽입: 제공자별 호환성 처리를 통해 모든 요청에 ​​구성 가능한 시스템 프롬프트를 추가하거나 추가합니다. | -| `thinkingBudget.ts` | 추론 토큰 예산 관리: 사고/추론 토큰 제어를 위한 패스스루, 자동(스트립 사고 구성), 사용자 정의(고정 예산) 및 적응형(복잡성 확장) 모드를 지원합니다. | -| `wildcardRouter.ts` | 와일드카드 모델 패턴 라우팅: 가용성 및 우선순위에 따라 와일드카드 패턴(예: `*/claude-*`)을 구체적인 공급자/모델 쌍으로 확인합니다. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### 토큰 새로 고침 중복 제거 +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### 계정 대체 상태 머신 +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### 콤보 모델 체인 +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 번역기(`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -자체 등록 플러그인 시스템을 사용하는 **형식 번역 엔진**. +The **format translation engine** using a self-registering plugin system. -#### 아키텍처 +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| 디렉토리 | 파일 | 설명 | -| ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8명의 번역가 | 형식 간에 요청 본문을 변환합니다. 각 파일은 가져올 때 `register(from, to, fn)`을 통해 자체 등록됩니다. | -| `response/` | 7명의 번역자 | 형식 간에 스트리밍 응답 청크를 변환합니다. SSE 이벤트 유형, 사고 블록, 도구 호출을 처리합니다. | -| `helpers/` | 도우미 6명 | 공유 유틸리티: `claudeHelper`(시스템 프롬프트 추출, 사고 구성), `geminiHelper`(부분/콘텐츠 매핑), `openaiHelper`(형식 필터링), `toolCallHelper`(ID 생성, 누락된 응답 주입), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | 번역 엔진: `translateRequest()`, `translateResponse()`, 상태 관리, 레지스트리. | -| `formats.ts` | — | 형식 상수: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### 주요 디자인: 자동 등록 플러그인 +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 유틸리티(`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| 파일 | 목적 | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | 오류 응답 구축(OpenAI 호환 형식), 업스트림 오류 구문 분석, 오류 메시지에서 반중력 재시도 시간 추출, SSE 오류 스트리밍. | -| `stream.ts` | **SSE 변환 스트림** — 핵심 스트리밍 파이프라인입니다. 두 가지 모드: `TRANSLATE`(전체 형식 번역) 및 `PASSTHROUGH`(정규화 + 사용량 추출). 청크 버퍼링, 사용량 추정, 콘텐츠 길이 추적을 처리합니다. 스트림별 인코더/디코더 인스턴스는 공유 상태를 방지합니다. | -| `streamHelpers.ts` | 하위 수준 SSE 유틸리티: `parseSSELine`(공백 허용), `hasValuableContent`(OpenAI/Claude/Gemini의 빈 청크 필터링), `fixInvalidId`, `formatSSE`(`perf_metrics` 정리를 통한 형식 인식 SSE 직렬화). | -| `usageTracking.ts` | 모든 형식(Claude/OpenAI/Gemini/Responses)에서 토큰 사용량 추출, 별도 도구/토큰당 메시지 문자 비율을 사용한 추정, 버퍼 추가(2000 토큰 안전 마진), 형식별 필드 필터링, ANSI 색상을 사용한 콘솔 로깅. | -| `requestLogger.ts` | 파일 기반 요청 로깅(`ENABLE_REQUEST_LOGS=true`을 통한 선택). 번호가 매겨진 파일(`1_req_client.json` → `7_res_client.txt`)로 세션 폴더를 생성합니다. 모든 I/O는 비동기식입니다(fire-and-forget). 민감한 헤더를 마스킹합니다. | -| `bypassHandler.ts` | Claude CLI(제목 추출, 워밍업, 카운트)의 특정 패턴을 가로채고 공급자를 호출하지 않고 가짜 응답을 반환합니다. 스트리밍과 비스트리밍을 모두 지원합니다. 의도적으로 Claude CLI 범위로 제한되었습니다. | -| `networkProxy.ts` | 공급자별 구성 → 전역 구성 → 환경 변수(`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`) 우선 순위에 따라 지정된 공급자에 대한 아웃바운드 프록시 URL을 확인합니다. `NO_PROXY` 제외를 지원합니다. 30초 동안 캐시 구성. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### SSE 스트리밍 파이프라인 +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### 요청 로거 세션 구조 +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 애플리케이션 계층(`src/`) +### 4.7 Application Layer (`src/`) -| 디렉토리 | 목적 | -| ------------- | ------------------------------------------------------------------- | -| `src/app/` | 웹 UI, API 경로, Express 미들웨어, OAuth 콜백 핸들러 | -| `src/lib/` | 데이터베이스 액세스(`localDb.ts`, `usageDb.ts`), 인증, 공유 | -| `src/mitm/` | 공급자 트래픽을 가로채기 위한 중간자 프록시 유틸리티 | -| `src/models/` | 데이터베이스 모델 정의 | -| `src/shared/` | open-sse 함수에 대한 래퍼(공급자, 스트림, 오류 등) | -| `src/sse/` | open-sse 라이브러리를 Express 경로에 연결하는 SSE 엔드포인트 핸들러 | -| `src/store/` | 애플리케이션 상태 관리 | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### 주목할만한 API 경로 +#### Notable API Routes -| 경로 | 방법 | 목적 | -| --------------------------------------------- | ------------------ | -------------------------------------------------------------------------------- | -| `/api/provider-models` | 가져오기/게시/삭제 | 공급자별 사용자 정의 모델을 위한 CRUD | -| `/api/models/catalog` | 받기 | 공급자별로 그룹화된 모든 모델(채팅, 임베딩, 이미지, 사용자 정의)의 집계 카탈로그 | -| `/api/settings/proxy` | 가져오기/넣기/삭제 | 계층적 아웃바운드 프록시 구성(`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | 포스트 | 프록시 연결을 확인하고 공용 IP/지연 시간을 반환합니다. | -| `/v1/providers/[provider]/chat/completions` | 포스트 | 모델 검증을 통한 제공업체별 전용 채팅 완료 | -| `/v1/providers/[provider]/embeddings` | 포스트 | 모델 검증을 통한 제공자별 전용 임베딩 | -| `/v1/providers/[provider]/images/generations` | 포스트 | 모델 검증을 통한 제공자별 전용 이미지 생성 | -| `/api/settings/ip-filter` | 가져오기/넣기 | IP 허용 목록/차단 목록 관리 | -| `/api/settings/thinking-budget` | 가져오기/넣기 | 토큰 예산 구성 추론(통과/자동/맞춤/적응) | -| `/api/settings/system-prompt` | 가져오기/넣기 | 모든 요청에 ​​대해 글로벌 시스템 프롬프트 주입 | -| `/api/sessions` | 받기 | 활성 세션 추적 및 측정항목 | -| `/api/rate-limits` | 받기 | 계정별 비율한도 현황 | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. 주요 디자인 패턴 +## 5. Key Design Patterns -### 5.1 허브 앤 스포크 번역 +### 5.1 Hub-and-Spoke Translation -모든 형식은 **OpenAI 형식을 허브**로 통해 변환됩니다. 새 공급자를 추가하려면 N 쌍이 아닌 **한 쌍**의 번역기(OpenAI 간)만 작성하면 됩니다. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 실행자 전략 패턴 +### 5.2 Executor Strategy Pattern -각 공급자에는 `BaseExecutor`에서 상속되는 전용 실행자 클래스가 있습니다. `executors/index.ts`의 팩토리는 런타임 시 올바른 팩토리를 선택합니다. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 자체 등록 플러그인 시스템 +### 5.3 Self-Registering Plugin System -번역기 모듈은 `register()`을 통해 가져올 때 자체적으로 등록됩니다. 새로운 번역자를 추가하는 것은 파일을 생성하고 가져오는 것뿐입니다. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 지수 백오프를 사용한 계정 대체 +### 5.4 Account Fallback with Exponential Backoff -공급자가 429/401/500을 반환하면 시스템은 지수 쿨다운(1초 → 2초 → 4초 → 최대 2분)을 적용하여 다음 계정으로 전환할 수 있습니다. +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 콤보 모델 체인 +### 5.5 Combo Model Chains -"콤보"는 여러 `provider/model` 문자열을 그룹화합니다. 첫 번째 작업이 실패하면 자동으로 다음 작업으로 대체됩니다. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 상태 저장 스트리밍 변환 +### 5.6 Stateful Streaming Translation -응답 변환은 `initState()` 메커니즘을 통해 SSE 청크(사고 블록 추적, 도구 호출 축적, 콘텐츠 블록 인덱싱) 전체에서 상태를 유지합니다. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 사용 안전 버퍼 +### 5.7 Usage Safety Buffer -클라이언트가 시스템 프롬프트 및 형식 변환의 오버헤드로 인해 컨텍스트 창 제한에 도달하는 것을 방지하기 위해 보고된 사용량에 2000토큰 버퍼가 추가되었습니다. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. 지원되는 형식 +## 6. Supported Formats -| 형식 | 방향 | 식별자 | -| ---------------- | ----------- | ------------------ | -| OpenAI 채팅 완료 | 소스 + 타겟 | `openai` | -| OpenAI 응답 API | 소스 + 타겟 | `openai-responses` | -| 인류학 클로드 | 소스 + 타겟 | `claude` | -| 구글 제미니 | 소스 + 타겟 | `gemini` | -| 구글 제미니 CLI | 대상만 | `gemini-cli` | -| 반중력 | 소스 + 타겟 | `antigravity` | -| AWS 키로 | 대상만 | `kiro` | -| 커서 | 대상만 | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. 지원되는 공급자 +## 7. Supported Providers -| 공급자 | 인증 방법 | 집행자 | 주요 내용 | -| ------------------------ | ---------------------- | --------- | ------------------------------------------- | -| 인류학 클로드 | API 키 또는 OAuth | 기본값 | `x-api-key` 헤더 사용 | -| 구글 제미니 | API 키 또는 OAuth | 기본값 | `x-goog-api-key` 헤더 사용 | -| 구글 제미니 CLI | OAuth | 쌍둥이CLI | `streamGenerateContent` 엔드포인트 사용 | -| 반중력 | OAuth | 반중력 | 다중 URL 대체, 사용자 정의 재시도 구문 분석 | -| 오픈AI | API 키 | 기본값 | 표준 무기명 인증 | -| 코덱스 | OAuth | 코덱스 | 시스템 지침 주입, ​​사고 관리 | -| GitHub 부조종사 | OAuth + Copilot 토큰 | 깃허브 | 듀얼 토큰, VSCode 헤더 모방 | -| 키로(AWS) | AWS SSO OIDC 또는 소셜 | 키로 | 바이너리 EventStream 구문 분석 | -| 커서 IDE | 체크섬 인증 | 커서 | Protobuf 인코딩, SHA-256 체크섬 | -| 퀀 | OAuth | 기본값 | 표준 인증 | -| 아이플로우 | OAuth(기본 + 전달자) | 기본값 | 이중 인증 헤더 | -| 오픈라우터 | API 키 | 기본값 | 표준 무기명 인증 | -| GLM, 키미, 미니맥스 | API 키 | 기본값 | Claude 호환, `x-api-key` 사용 | -| `openai-compatible-*` | API 키 | 기본값 | 동적: 모든 OpenAI 호환 엔드포인트 | -| `anthropic-compatible-*` | API 키 | 기본값 | 동적: Claude와 호환되는 모든 엔드포인트 | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. 데이터 흐름 요약 +## 8. Data Flow Summary -### 스트리밍 요청 +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### 비스트리밍 요청 +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### 우회 흐름(Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/ko/FEATURES.md b/docs/i18n/ko/FEATURES.md index d4c87a1b25..82cc73b67b 100644 --- a/docs/i18n/ko/FEATURES.md +++ b/docs/i18n/ko/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — 대시보드 기능 갤러리 +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -OmniRoute 대시보드의 모든 섹션에 대한 시각적 가이드입니다. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 제공업체 +## 🔌 Providers -AI 공급자 연결 관리: OAuth 공급자(Claude Code, Codex, Gemini CLI), API 키 공급자(Groq, DeepSeek, OpenRouter) 및 무료 공급자(iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 콤보 +## 🎨 Combos -채우기 우선, 라운드 로빈, 두 가지 선택의 힘, 무작위, 최소 사용, 비용 최적화 등 6가지 전략을 사용하여 모델 라우팅 콤보를 만듭니다. 각 콤보는 자동 폴백을 통해 여러 모델을 연결합니다. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 분석 +## 📊 Analytics -토큰 소비, 비용 추정, 활동 히트맵, 주간 분포 차트 및 공급자별 분석을 포함한 포괄적인 사용량 분석입니다. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 시스템 상태 +## 🏥 System Health -실시간 모니터링: 가동 시간, 메모리, 버전, 대기 시간 백분위수(p50/p95/p99), 캐시 통계 및 공급자 회로 차단기 상태. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 번역기 놀이터 +## 🔧 Translator Playground -API 번역 디버깅을 위한 4가지 모드: **플레이그라운드**(형식 변환기), **채팅 테스터**(실시간 요청), **테스트 벤치**(일괄 테스트), **라이브 모니터**(실시간 스트림). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ 설정 +## 🎮 Model Playground _(v2.0.9+)_ -일반 설정, 시스템 스토리지, 백업 관리(데이터베이스 내보내기/가져오기), 모양(어둡게/밝게 모드), 보안(API 엔드포인트 보호 및 사용자 정의 공급자 차단 포함), 라우팅, 복원력 및 고급 구성. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI 도구 +## 🔧 CLI Tools -AI 코딩 도구에 대한 원클릭 구성: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code 및 Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 요청 로그 +## 🤖 CLI Agents _(v2.0.11+)_ -공급자, 모델, 계정 및 API 키별로 필터링하여 실시간 요청 로깅. 상태 코드, 토큰 사용량, 대기 시간 및 응답 세부 정보를 표시합니다. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API 엔드포인트 +## 🌐 API Endpoint -기능 분석이 포함된 통합 API 엔드포인트: 채팅 완료, 임베딩, 이미지 생성, 순위 재지정, 오디오 전사 및 등록된 API 키. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ko/TROUBLESHOOTING.md b/docs/i18n/ko/TROUBLESHOOTING.md index 5bd3942d42..120092d63c 100644 --- a/docs/i18n/ko/TROUBLESHOOTING.md +++ b/docs/i18n/ko/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# 문제 해결 +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -OmniRoute의 일반적인 문제 및 솔루션. +Common problems and solutions for OmniRoute. --- -## 빠른 수정 +## Quick Fixes -| 문제 | 솔루션 | -| ----------------------------------- | ------------------------------------------------------------------- | -| 첫 번째 로그인이 작동하지 않습니다 | `.env`에서 `INITIAL_PASSWORD` 확인(기본값: `123456`) | -| 대시보드가 ​​잘못된 포트에서 열림 | `PORT=20128` 및 `NEXT_PUBLIC_BASE_URL=http://localhost:20128` 설정 | -| `logs/` 아래에 요청 로그가 없습니다 | `ENABLE_REQUEST_LOGS=true` 설정 | -| EACCES: 권한이 거부되었습니다 | `DATA_DIR=/path/to/writable/dir`을 설정하여 `~/.omniroute`을 재정의 | -| 라우팅 전략이 저장되지 않음 | v1.4.11+로 업데이트(설정 지속성을 위한 Zod 스키마 수정) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## 공급자 문제 +## Provider Issues -### "언어 모델이 메시지를 제공하지 않았습니다." +### "Language model did not provide messages" -**원인:** 공급자 할당량이 소진되었습니다. +**Cause:** Provider quota exhausted. -**수정:** +**Fix:** -1. 대시보드 할당량 추적기를 확인하세요. -2. 대체 계층과 콤보 사용 -3. 더 저렴한/무료 등급으로 전환 +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### 속도 제한 +### Rate Limiting -**원인:** 구독 할당량이 소진되었습니다. +**Cause:** Subscription quota exhausted. -**수정:** +**Fix:** -- 대체 추가: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- GLM/MiniMax를 저렴한 백업으로 사용 +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth 토큰 만료됨 +### OAuth Token Expired -OmniRoute는 토큰을 자동으로 새로 고칩니다. 문제가 지속되는 경우: +OmniRoute auto-refreshes tokens. If issues persist: -1. 대시보드 → 공급자 → 재접속 -2. 공급자 연결을 삭제하고 다시 추가 +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## 클라우드 문제 +## Cloud Issues -### 클라우드 동기화 오류 +### Cloud Sync Errors -1. `BASE_URL`이 실행 중인 인스턴스(예: `http://localhost:20128`)를 가리키는지 확인합니다. -2. `CLOUD_URL`이 클라우드 엔드포인트(예: `https://omniroute.dev`)를 가리키는지 확인하세요. -3. `NEXT_PUBLIC_*` 값을 서버측 값에 맞춰 유지하세요. +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### 클라우드 `stream=false` 500을 반환합니다. +### Cloud `stream=false` Returns 500 -**증상:** 비스트리밍 통화에 대한 클라우드 엔드포인트의 `Unexpected token 'd'...`. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**원인:** 업스트림은 클라이언트가 JSON을 기대하는 동안 SSE 페이로드를 반환합니다. +**Cause:** Upstream returns SSE payload while client expects JSON. -**해결 방법:** 클라우드 직접 호출에는 `stream=true`을 사용하세요. 로컬 런타임에는 SSE→JSON 대체가 포함됩니다. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### 클라우드가 연결되었지만 "잘못된 API 키"라고 표시됩니다. +### Cloud Says Connected but "Invalid API key" -1. 로컬 대시보드(`/api/keys`)에서 새로운 키를 생성합니다. -2. 클라우드 동기화 실행: 클라우드 활성화 → 지금 동기화 -3. 이전/동기화되지 않은 키는 여전히 클라우드에서 `401`을 반환할 수 있습니다. +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## 도커 문제 +## Docker Issues -### CLI 도구가 설치되지 않은 것으로 표시됨 +### CLI Tool Shows Not Installed -1. 런타임 필드 확인: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. 휴대용 모드의 경우: 이미지 대상 `runner-cli` 사용(번들 CLI) -3. 호스트 마운트 모드의 경우: `CLI_EXTRA_PATHS`을 설정하고 호스트 bin 디렉터리를 읽기 전용으로 마운트합니다. -4. `installed=true` 및 `runnable=false`인 경우: 바이너리가 발견되었지만 상태 확인에 실패했습니다. +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### 빠른 런타임 검증 +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## 비용 문제 +## Cost Issues -### 높은 비용 +### High Costs -1. 대시보드 → 사용량에서 사용량 현황을 확인하세요. -2. 기본 모델을 GLM/MiniMax로 전환 -3. 중요하지 않은 작업에는 무료 계층(Gemini CLI, iFlow)을 사용합니다. -4. API 키별 비용 예산 설정: 대시보드 → API 키 → 예산 +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## 디버깅 +## Debugging -### 요청 로그 활성화 +### Enable Request Logs -`.env` 파일에 `ENABLE_REQUEST_LOGS=true`을 설정합니다. 로그는 `logs/` 디렉터리에 나타납니다. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### 제공자 상태 확인 +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### 런타임 스토리지 +### Runtime Storage -- 기본 상태: `${DATA_DIR}/db.json`(공급자, 콤보, 별칭, 키, 설정) -- 사용법: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- 요청 로그: `/logs/...`(`ENABLE_REQUEST_LOGS=true`인 경우) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## 회로 차단기 문제 +## Circuit Breaker Issues -### 제공자가 OPEN 상태에서 멈췄습니다. +### Provider stuck in OPEN state -공급자의 회로 차단기가 OPEN되면 대기 시간이 만료될 때까지 요청이 차단됩니다. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**수정:** +**Fix:** -1. **대시보드 → 설정 → 복원력**으로 이동합니다. -2. 영향을 받는 공급자의 회로 차단기 카드를 확인하십시오. -3. **모두 재설정**을 클릭하여 모든 차단기를 삭제하거나 쿨다운이 만료될 때까지 기다립니다. -4. 재설정하기 전에 공급자가 실제로 사용 가능한지 확인하십시오. +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### 공급업체가 계속해서 회로 차단기를 작동시킵니다. +### Provider keeps tripping the circuit breaker -공급자가 반복적으로 OPEN 상태에 들어가는 경우: +If a provider repeatedly enters OPEN state: -1. **대시보드 → 상태 → 공급자 상태**에서 실패 패턴을 확인합니다. -2. **설정 → 탄력성 → 공급자 프로필**로 이동하여 실패 임계값을 높입니다. -3. 제공업체가 API 한도를 변경했는지 또는 재인증을 요구하는지 확인하세요. -4. 대기 시간 원격 분석 검토 - 대기 시간이 길면 시간 초과 기반 오류가 발생할 수 있습니다. +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## 오디오 전사 문제 +## Audio Transcription Issues -### "지원되지 않는 모델" 오류 +### "Unsupported model" error -- 올바른 접두사(`deepgram/nova-3` 또는 `assemblyai/best`)를 사용하고 있는지 확인하세요. -- **대시보드 → 공급자**에서 공급자가 연결되어 있는지 확인합니다. +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### 전사가 비어 있거나 실패함을 반환합니다. +### Transcription returns empty or fails -- 지원되는 오디오 형식 확인: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- 파일 크기가 공급자 제한(일반적으로 < 25MB) 내에 있는지 확인하세요. -- 공급자 카드에서 공급자 API 키 유효성을 확인하세요. +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## 번역기 디버깅 +## Translator Debugging -**대시보드 → 번역기**를 사용하여 형식 번역 문제를 디버깅하세요. +Use **Dashboard → Translator** to debug format translation issues: -| 모드 | 사용 시기 | -| ----------------- | ---------------------------------------------------------------------------------------- | -| **놀이터** | 입력/출력 형식을 나란히 비교하세요. 실패한 요청을 붙여넣어 어떻게 변환되는지 확인하세요. | -| **채팅 테스터** | 실시간 메시지 보내기 및 헤더를 포함한 전체 요청/응답 페이로드 검사 | -| **테스트 벤치** | 형식 조합 전반에 걸쳐 일괄 테스트를 실행하여 어떤 번역이 손상되었는지 확인 | -| **라이브 모니터** | 간헐적인 번역 문제를 파악하기 위해 실시간 요청 흐름을 시청하세요 | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### 일반적인 형식 문제 +### Common format issues -- **Thinking 태그가 표시되지 않음** — 대상 공급자가 Thinking을 지원하는지 및 Thinking 예산 설정을 확인하세요. -- **도구 호출 중단** — 일부 형식 번역은 지원되지 않는 필드를 제거할 수 있습니다. 플레이그라운드 모드에서 확인 -- **시스템 프롬프트 누락** — Claude와 Gemini는 시스템 프롬프트를 다르게 처리합니다. 번역 출력 확인 -- **SDK는 객체 대신 원시 문자열을 반환** — v1.1.0에서 수정됨: 응답 새니타이저는 이제 OpenAI SDK Pydantic 검증 실패를 유발하는 비표준 필드(`x_groq`, `usage_breakdown` 등)를 제거합니다. -- **GLM/ERNIE는 `system` 역할을 거부합니다** — v1.1.0에서 수정됨: 역할 정규화 프로그램이 호환되지 않는 모델에 대한 시스템 메시지를 사용자 메시지에 자동으로 병합합니다. -- **`developer` 역할이 인식되지 않음** — v1.1.0에서 수정됨: OpenAI가 아닌 제공업체의 경우 자동으로 `system`로 변환됨 -- **`json_schema`가 Gemini와 작동하지 않음** — v1.1.0에서 수정됨: `response_format`은 이제 Gemini의 `responseMimeType` + `responseSchema`로 변환됩니다. +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## 복원력 설정 +## Resilience Settings -### 자동 비율 제한이 실행되지 않음 +### Auto rate-limit not triggering -- 자동 비율 제한은 API 키 제공자에게만 적용됩니다(OAuth/구독 제외). -- **설정 → 탄력성 → 공급자 프로필**에 자동 속도 제한이 활성화되어 있는지 확인하세요. -- 공급자가 `429` 상태 코드 또는 `Retry-After` 헤더를 반환하는지 확인하세요. +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### 지수 백오프 조정 +### Tuning exponential backoff -공급자 프로필은 다음 설정을 지원합니다. +Provider profiles support these settings: -- **기본 지연** — 첫 번째 실패 후 초기 대기 시간(기본값: 1초) -- **최대 지연** — 최대 대기 시간 한도(기본값: 30초) -- **승수** — 연속 실패당 지연을 늘리는 정도(기본값: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### 천둥 방지 무리 +### Anti-thundering herd -많은 동시 요청이 속도 제한 공급자에 도달하면 OmniRoute는 뮤텍스와 자동 속도 제한을 사용하여 요청을 직렬화하고 계단식 오류를 방지합니다. API 키 제공자의 경우 이는 자동입니다. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## 아직도 막혔나요? +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub 문제**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **아키텍처**: 내부 세부정보는 [link](ARCHITECTURE.md)을 참조하세요. -- **API 참조**: 모든 엔드포인트에 대해서는 [link](API_REFERENCE.md)을 참조하세요. -- **헬스 대시보드**: **대시보드 → 헬스**에서 실시간 시스템 상태 확인 -- **번역기**: **대시보드 → 번역기**를 사용하여 형식 문제 디버깅 +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/ko/USER_GUIDE.md b/docs/i18n/ko/USER_GUIDE.md index 196c9ad0d3..5a043224df 100644 --- a/docs/i18n/ko/USER_GUIDE.md +++ b/docs/i18n/ko/USER_GUIDE.md @@ -1,12 +1,12 @@ -# 이용안내 +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -공급자 구성, 콤보 생성, CLI 도구 통합 및 OmniRoute 배포에 대한 전체 가이드입니다. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## 목차 +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 가격 한눈에 보기 +## 💰 Pricing at a Glance -| 계층 | 공급자 | 비용 | 할당량 재설정 | 최고의 대상 | -| ------------- | ------------------- | ------------------ | --------------- | ----------------- | -| **💳 구독** | 클로드 코드 (Pro) | $20/월 | 5시간 + 매주 | 이미 구독 중 | -| | 코덱스(플러스/프로) | $20-200/월 | 5시간 + 매주 | OpenAI 사용자 | -| | 제미니 CLI | **무료** | 180K/월 + 1K/일 | 모든 사람! | -| | GitHub 부조종사 | $10-19/월 | 월간 | GitHub 사용자 | -| **🔑 API 키** | 딥시크 | 사용량에 따라 지불 | 없음 | 저렴한 추론 | -| | 그로크 | 사용량에 따라 지불 | 없음 | 초고속 추론 | -| | xAI(그록) | 사용량에 따라 지불 | 없음 | Grok 4 추론 | -| | 미스트랄 | 사용량에 따라 지불 | 없음 | EU 주최 모델 | -| | 당혹감 | 사용량에 따라 지불 | 없음 | 검색 증강 | -| | 함께하는 AI | 사용량에 따라 지불 | 없음 | 오픈 소스 모델 | -| | 불꽃놀이 AI | 사용량에 따라 지불 | 없음 | 빠른 FLUX 이미지 | -| | 대뇌 | 사용량에 따라 지불 | 없음 | 웨이퍼 규모 속도 | -| | 코히어 | 사용량에 따라 지불 | 없음 | 커맨드 R+ RAG | -| | 엔비디아 NIM | 사용량에 따라 지불 | 없음 | 엔터프라이즈 모델 | -| **💰 저렴한** | GLM-4.7 | $0.6/1M | 매일 오전 10시 | 예산 백업 | -| | 미니맥스 M2.1 | $0.2/1M | 5시간 롤링 | 가장 저렴한 옵션 | -| | 키미 K2 | $9/월 정액 | 1000만 토큰/월 | 예측 가능한 비용 | -| **🆓 무료** | 아이플로우 | $0 | 무제한 | 8개 모델 무료 | -| | 퀀 | $0 | 무제한 | 3개 모델 무료 | -| | 키로 | $0 | 무제한 | 클로드 프리 | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 전문가 팁:** Gemini CLI(월 180K 무료) + iFlow(무제한 무료) 콤보 = 비용 $0로 시작하세요! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 사용 사례 +## 🎯 Use Cases -### 사례 1: "Claude Pro를 구독하고 있습니다." +### Case 1: "I have Claude Pro subscription" -**문제:** 할당량은 사용되지 않은 상태로 만료되며, 코딩 작업이 많은 동안 속도 제한이 발생합니다. +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### 사례 2: "비용이 0이길 원합니다" +### Case 2: "I want zero cost" -**문제:** 구독료를 감당할 수 없고 안정적인 AI 코딩이 필요함 +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### 사례 3: "중단 없이 연중무휴 코딩이 필요합니다." +### Case 3: "I need 24/7 coding, no interruptions" -**문제:** 마감일, 가동 중지 시간을 감당할 수 없음 +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### 사례 4: "OpenClaw에서 무료 AI를 원합니다" +### Case 4: "I want FREE AI in OpenClaw" -**문제:** 메시징 앱에 AI 도우미가 필요하며 완전 무료입니다. +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 공급자 설정 +## 📖 Provider Setup -### 🔐 구독 제공업체 +### 🔐 Subscription Providers -#### 클로드 코드(Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**프로 팁:** 복잡한 작업에는 Opus를 사용하고, 속도를 높이려면 Sonnet을 사용하세요. OmniRoute는 모델당 할당량을 추적합니다! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### OpenAI 코덱스(Plus/Pro) +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI(월 180K 무료!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**최고의 가치:** 엄청난 무료 등급! 유료 등급 이전에 사용하세요. +**Best Value:** Huge free tier! Use this before paid tiers. -#### GitHub 코파일럿 +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 저렴한 공급자 +### 💰 Cheap Providers -#### GLM-4.7 (일일 재설정, $0.6/1M) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. 가입: [Zhipu AI](https://open.bigmodel.cn/) -2. Coding Plan에서 API Key 받기 -3. 대시보드 → API 키 추가: 공급자: `glm`, API 키: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**사용:** `glm/glm-4.7` — **프로 팁:** 코딩 계획은 1/7 비용으로 3배 할당량을 제공합니다! 매일 오전 10시에 초기화됩니다. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1(5시간 재설정, $0.20/1M) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. 가입: [MiniMax](https://www.minimax.io/) -2. API 키 받기 → 대시보드 → API 키 추가 +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**사용:** `minimax/MiniMax-M2.1` — **프로 팁:** 긴 컨텍스트(1M 토큰)에 대한 가장 저렴한 옵션! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2($9/월 정액) +#### Kimi K2 ($9/month flat) -1. 구독: [Moonshot AI](https://platform.moonshot.ai/) -2. API 키 받기 → 대시보드 → API 키 추가 +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**사용:** `kimi/kimi-latest` — **프로 팁:** 1,000만 토큰에 대해 월 $9 고정 = 유효 비용 $0.90/1M! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 무료 제공업체 +### 🆓 FREE Providers -#### iFlow(8개 무료 모델) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen(3개 무료 모델) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### 키로(클로드 프리) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 콤보 +## 🎨 Combos -### 예시 1: 구독 최대화 → 저렴한 백업 +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### 예시 2: 무료 전용(비용 없음) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI 통합 +## 🔧 CLI Integration -### 커서 IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### 클로드 코드 +### Claude Code -`~/.claude/config.json` 편집: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Settings → Models → Advanced: } ``` -### 코덱스 CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -279,9 +279,9 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### 오픈클로 +### OpenClaw -`~/.openclaw/openclaw.json` 편집: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ codex "your prompt" } ``` -**또는 대시보드 사용:** CLI 도구 → OpenClaw → 자동 구성 +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### 클라인 / 계속 / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 배포 +## 🚀 Deployment -### VPS 배포 +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### 도커 +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,81 +403,84 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -CLI 바이너리를 사용한 호스트 통합 모드의 경우 기본 문서의 Docker 섹션을 참조하세요. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### 환경 변수 +### Environment Variables -| 변수 | 기본값 | 설명 | -| --------------------- | ------------------------------------ | ----------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 서명 비밀(**프로덕션 변경**) | -| `INITIAL_PASSWORD` | `123456` | 첫 번째 로그인 비밀번호 | -| `DATA_DIR` | `~/.omniroute` | 데이터 디렉터리(db, 사용량, 로그) | -| `PORT` | 프레임워크 기본값 | 서비스 포트(예시에서는 `20128`) | -| `HOSTNAME` | 프레임워크 기본값 | 호스트 바인딩(Docker의 기본값은 `0.0.0.0`) | -| `NODE_ENV` | 런타임 기본값 | 배포를 위해 `production` 설정 | -| `BASE_URL` | `http://localhost:20128` | 서버측 내부 기본 URL | -| `CLOUD_URL` | `https://omniroute.dev` | 클라우드 동기화 엔드포인트 기본 URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | 생성된 API 키에 대한 HMAC 비밀 | -| `REQUIRE_API_KEY` | `false` | `/v1/*`에 Bearer API 키 적용 | -| `ENABLE_REQUEST_LOGS` | `false` | 요청/응답 로그 활성화 | -| `AUTH_COOKIE_SECURE` | `false` | `Secure` 인증 쿠키 강제(HTTPS 역방향 프록시 뒤) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -전체 환경 변수 참조는 [README](../README.md)을 참조하세요. +For the full environment variable reference, see the [README](../README.md). --- -## 📊 사용 가능한 모델 +## 📊 Available Models
-사용 가능한 모든 모델 보기 +View all available models -**Claude 코드(`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**코덱스(`cx/`)** — 플러스/프로: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI(`gc/`)** — 무료: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**GitHub 부조종사(`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` **GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax(`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow(`if/`)** — 무료: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen(`qw/`)** — 무료: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**키로(`kr/`)** — 무료: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` -**DeepSeek(`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` -**그로크(`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` -**xAI(`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` +**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**미스트랄(`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**복잡성(`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**함께하는 AI(`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**불꽃놀이 AI(`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**대뇌(`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Cohere(`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` -**NVIDIA NIM(`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
--- -## 🧩 고급 기능 +## 🧩 Advanced Features -### 맞춤 모델 +### Custom Models -앱 업데이트를 기다리지 않고 공급자에 모델 ID를 추가하세요. +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -또는 대시보드를 사용하십시오: **공급자 → [공급자] → 사용자 정의 모델**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### 전용 공급자 경로 +### Dedicated Provider Routes -모델 검증을 통해 요청을 특정 공급자에게 직접 라우팅합니다. +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -공급자 접두사가 누락된 경우 자동으로 추가됩니다. 일치하지 않는 모델은 `400`을 반환합니다. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### 네트워크 프록시 구성 +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**우선순위:** 키별 → 콤보별 → 공급자별 → 글로벌 → 환경. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### 모델 카탈로그 API +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -유형(`chat`, `embedding`, `image`)을 사용하여 공급자별로 그룹화된 모델을 반환합니다. +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### 클라우드 동기화 +### Cloud Sync -- 여러 장치에서 공급자, 콤보 및 설정을 동기화합니다. -- 시간 초과 + 빠른 실패를 통한 자동 백그라운드 동기화 -- 프로덕션에서는 서버측 `BASE_URL`/`CLOUD_URL`을 선호합니다. +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM 게이트웨이 인텔리전스(9단계) +### LLM Gateway Intelligence (Phase 9) -- **의미 체계 캐시** — 비스트리밍, 온도=0 응답을 자동 캐시합니다(`X-OmniRoute-No-Cache: true`으로 우회). -- **Idempotency 요청** — `Idempotency-Key` 또는 `X-Request-Id` 헤더를 통해 5초 이내에 요청을 중복 제거합니다. -- **진행 상황 추적** — `X-OmniRoute-Progress: true` 헤더를 통한 SSE `event: progress` 이벤트 선택 +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### 번역가 놀이터 +### Translator Playground -**대시보드 → 번역기**를 통해 액세스합니다. OmniRoute가 공급자 간 API 요청을 변환하는 방법을 디버깅하고 시각화합니다. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| 모드 | 목적 | -| ----------------- | ------------------------------------------------------------------------- | -| **놀이터** | 소스/타겟 형식을 선택하고, 요청을 붙여넣고, 번역된 결과를 즉시 확인하세요 | -| **채팅 테스터** | 프록시를 통해 실시간 채팅 메시지를 보내고 전체 요청/응답 주기 검사 | -| **테스트 벤치** | 여러 형식 조합에 걸쳐 일괄 테스트를 실행하여 번역 정확성 확인 | -| **라이브 모니터** | 프록시를 통한 요청 흐름에 따라 실시간 번역 보기 | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**사용 사례:** +**Use cases:** -- 특정 클라이언트/공급자 조합이 실패하는 이유 디버그 -- 생각 태그, 도구 호출 및 시스템 프롬프트가 올바르게 번역되는지 확인합니다. -- OpenAI, Claude, Gemini 및 Responses API 형식 간의 형식 차이 비교 +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### 라우팅 전략 +### Routing Strategies -**대시보드 → 설정 → 라우팅**을 통해 구성합니다. +Configure via **Dashboard → Settings → Routing**. -| 전략 | 설명 | -| -------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -| **먼저 채우기** | 우선순위에 따라 계정을 사용합니다. 기본 계정은 사용할 수 없을 때까지 모든 요청을 처리합니다. | -| **라운드 로빈** | 구성 가능한 고정 한도를 사용하여 모든 계정을 순환합니다(기본값: 계정당 호출 3회) | -| **P2C(두 가지 선택의 힘)** | 2개의 무작위 계정을 선택하고 더 건강한 계정으로 라우팅 — 건강에 대한 인식과 부하의 균형을 유지 | -| **랜덤** | Fisher-Yates shuffle | 을 사용하여 각 요청에 대해 무작위로 계정을 선택합니다. | -| **최소 사용** | 가장 오래된 `lastUsedAt` 타임스탬프가 있는 계정으로 라우팅하여 트래픽을 균등하게 분산 | -| **비용 최적화** | 가장 낮은 비용의 공급자를 위해 최적화하여 우선순위 값이 가장 낮은 계정으로 라우팅 | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### 와일드카드 모델 별칭 +#### Wildcard Model Aliases -모델 이름을 다시 매핑하는 와일드카드 패턴을 만듭니다. +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -와일드카드는 `*`(모든 문자) 및 `?`(단일 문자)을 지원합니다. +Wildcards support `*` (any characters) and `?` (single character). -#### 대체 체인 +#### Fallback Chains -모든 요청에 적용되는 전역 대체 체인을 정의합니다. +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### 탄력성 및 회로 차단기 +### Resilience & Circuit Breakers -**대시보드 → 설정 → 복원력**을 통해 구성합니다. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute는 다음 네 가지 구성 요소를 사용하여 공급자 수준 복원력을 구현합니다. +OmniRoute implements provider-level resilience with four components: -1. **공급자 프로필** — 다음에 대한 공급자별 구성: - - 실패 임계값(개방 전 실패 횟수) - - 쿨다운 시간 - - 비율 제한 감지 감도 - - 지수 백오프 매개변수 +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **편집 가능한 속도 제한** — 대시보드에서 구성 가능한 시스템 수준 기본값: - - **분당 요청(RPM)** — 계정당 분당 최대 요청 수 - - **요청 간 최소 시간** — 요청 간 최소 간격(밀리초) - - **최대 동시 요청** — 계정당 최대 동시 요청 - - 수정하려면 **수정**을 클릭한 다음 **저장** 또는 **취소**를 클릭하세요. 값은 복원력 API를 통해 유지됩니다. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **회로 차단기** — 공급자별 오류를 추적하고 임계값에 도달하면 자동으로 회로를 엽니다. - - **CLOSED**(정상) — 요청 흐름이 정상적으로 진행됩니다. - - **OPEN** — 반복적인 실패 후 공급자가 일시적으로 차단됩니다. - - **HALF_OPEN** — 공급자가 복구되었는지 테스트 +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **정책 및 잠긴 식별자** - 회로 차단기 상태와 강제 잠금 해제 기능이 있는 잠긴 식별자를 표시합니다. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **비율 제한 자동 감지** — `429` 및 `Retry-After` 헤더를 모니터링하여 공급자 비율 제한에 도달하는 것을 사전에 방지합니다. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**프로 팁:** 공급자가 중단에서 복구될 때 **모두 재설정** 버튼을 사용하여 모든 회로 차단기와 쿨다운을 해제합니다. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### 데이터베이스 내보내기/가져오기 +### Database Export / Import -**대시보드 → 설정 → 시스템 및 스토리지**에서 데이터베이스 백업을 관리하세요. +Manage database backups in **Dashboard → Settings → System & Storage**. -| 액션 | 설명 | -| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **데이터베이스 내보내기** | 현재 SQLite 데이터베이스를 `.sqlite` 파일로 다운로드 | -| **모두 내보내기(.tar.gz)** | 데이터베이스, 설정, 콤보, 공급자 연결(자격 증명 없음), API 키 메타데이터를 포함한 전체 백업 아카이브를 다운로드합니다. | -| **데이터베이스 가져오기** | 현재 데이터베이스를 대체하려면 `.sqlite` 파일을 업로드하세요. 가져오기 전 백업이 자동으로 생성됩니다. | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**가져오기 유효성 검사:** 가져온 파일은 무결성(SQLite pragma 검사), 필수 테이블(`provider_connections`, `provider_nodes`, `combos`, `api_keys`) 및 크기(최대 100MB)에 대해 유효성이 검사됩니다. +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**사용 사례:** +**Use Cases:** -- 머신 간 OmniRoute 마이그레이션 -- 재해 복구를 위한 외부 백업 생성 -- 팀원 간 구성 공유(모두 내보내기 → 아카이브 공유) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### 설정 대시보드 +### Settings Dashboard -설정 페이지는 쉽게 탐색할 수 있도록 5개의 탭으로 구성되어 있습니다. +The settings page is organized into 5 tabs for easy navigation: -| 탭 | 내용 | -| ---------- | ------------------------------------------------------------------------------ | -| **보안** | 로그인/비밀번호 설정, IP 액세스 제어, `/models`에 대한 API 인증 및 공급자 차단 | -| **라우팅** | 글로벌 라우팅 전략(6개 옵션), 와일드카드 모델 별칭, 폴백 체인, 콤보 기본값 | -| **탄력성** | 공급자 프로필, 편집 가능한 속도 제한, 회로 차단기 상태, 정책 및 잠긴 식별자 | -| **AI** | 생각하는 예산 구성, 글로벌 시스템 프롬프트 주입, 프롬프트 캐시 통계 | -| **고급** | 글로벌 프록시 구성(HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### 비용 및 예산 관리 +### Costs & Budget Management -**대시보드 → 비용**을 통해 액세스합니다. +Access via **Dashboard → Costs**. -| 탭 | 목적 | -| -------- | ----------------------------------------------------------------- | -| **예산** | 일별/주별/월별 예산 및 실시간 추적을 통해 API 키별 지출 한도 설정 | -| **가격** | 모델 가격 항목 보기 및 편집 - 공급자당 1K 입력/출력 토큰당 비용 | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**비용 추적:** 모든 요청은 토큰 사용량을 기록하고 가격표를 사용하여 비용을 계산합니다. **대시보드 → 사용량**에서 공급자, 모델, API 키별 분석을 확인하세요. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### 오디오 전사 +### Audio Transcription -OmniRoute는 OpenAI 호환 엔드포인트를 통해 오디오 전사를 지원합니다. +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -사용 가능한 공급자: **Deepgram**(`deepgram/`), **AssemblyAI**(`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -지원되는 오디오 형식: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### 콤보 밸런싱 전략 +### Combo Balancing Strategies -**대시보드 → 콤보 → 생성/편집 → 전략**에서 콤보별 밸런싱을 구성하세요. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| 전략 | 설명 | -| -------------------- | ----------------------------------------------------------- | -| **라운드 로빈** | 모델을 순차적으로 회전 | -| **우선순위** | 항상 첫 번째 모델을 시도합니다. 오류가 발생한 경우에만 폴백 | -| **랜덤** | 각 요청에 대한 콤보에서 무작위 모델 선택 | -| **가중치** | 모델별로 할당된 가중치를 기준으로 비례적으로 라우팅 | -| **가장 적게 사용됨** | 최근 요청이 가장 적은 모델로 라우팅(콤보 메트릭 사용) | -| **비용 최적화** | 가장 저렴한 모델로 연결(가격표 사용) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -글로벌 콤보 기본값은 **대시보드 → 설정 → 라우팅 → 콤보 기본값**에서 설정할 수 있습니다. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### 건강 대시보드 +### Health Dashboard -**대시보드 → 건강**을 통해 액세스합니다. 6개의 카드를 사용한 실시간 시스템 상태 개요: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| 카드 | 표시되는 내용 | -| ------------------ | ----------------------------------------------- | -| **시스템 상태** | 가동 시간, 버전, 메모리 사용량, 데이터 디렉터리 | -| **제공자 건강** | 공급자별 회로 차단기 상태(폐쇄/개방/반개방) | -| **비율 제한** | 남은 시간에 따른 계정당 활성 속도 제한 쿨다운 | -| **활성 잠금** | 잠금 정책으로 인해 일시적으로 차단된 제공업체 | -| **서명 캐시** | 중복 제거 캐시 통계(활성 키, 적중률) | -| **지연 원격 측정** | 공급자별 p50/p95/p99 대기 시간 집계 | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**프로 팁:** 상태 페이지는 10초마다 자동으로 새로 고쳐집니다. 회로 차단기 카드를 사용하여 어떤 공급자가 문제를 겪고 있는지 식별하십시오. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/ms/API_REFERENCE.md b/docs/i18n/ms/API_REFERENCE.md index 625ac5f4db..b795722c11 100644 --- a/docs/i18n/ms/API_REFERENCE.md +++ b/docs/i18n/ms/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Rujukan API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Rujukan lengkap untuk semua titik akhir API OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Jadual Kandungan +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Rujukan lengkap untuk semua titik akhir API OmniRoute. --- -## Selesai Sembang +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Pengepala Tersuai +### Custom Headers -| Pengepala | Arah | Penerangan | -| ------------------------ | ------------ | ------------------------------------------- | -| `X-OmniRoute-No-Cache` | Permintaan | Tetapkan kepada `true` untuk memintas cache | -| `X-OmniRoute-Progress` | Permintaan | Tetapkan kepada `true` untuk acara kemajuan | -| `Idempotency-Key` | Permintaan | Kekunci dedup (tetingkap 5s) | -| `X-Request-Id` | Permintaan | Kunci pelupusan alternatif | -| `X-OmniRoute-Cache` | Maklum balas | `HIT` atau `MISS` (bukan penstriman) | -| `X-OmniRoute-Idempotent` | Maklum balas | `true` jika dinyahduplikasi | -| `X-OmniRoute-Progress` | Maklum balas | `enabled` jika penjejakan kemajuan pada | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Pembenaman +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Pembekal yang tersedia: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Penjanaan Imej +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Pembekal tersedia: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Senaraikan Model +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Titik Akhir Keserasian +## Compatibility Endpoints -| Kaedah | Laluan | Format | -| -------- | --------------------------- | ----------------------- | -| POS | `/v1/chat/completions` | OpenAI | -| POS | `/v1/messages` | Antroppik | -| POS | `/v1/responses` | Respons OpenAI | -| POS | `/v1/embeddings` | OpenAI | -| POS | `/v1/images/generations` | OpenAI | -| DAPATKAN | `/v1/models` | OpenAI | -| POS | `/v1/messages/count_tokens` | Antroppik | -| DAPATKAN | `/v1beta/models` | Gemini | -| POS | `/v1beta/models/{...path}` | Gemini menjanaKandungan | -| POS | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Laluan Penyedia Khusus +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Awalan pembekal ditambah secara automatik jika tiada. Model tidak sepadan mengembalikan `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Cache Semantik +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Contoh jawapan: +Response example: ```json { @@ -162,154 +162,164 @@ Contoh jawapan: --- -## Papan Pemuka & Pengurusan +## Dashboard & Management -### Pengesahan +### Authentication -| Titik akhir | Kaedah | Penerangan | -| ----------------------------- | -------------- | -------------------------- | -| `/api/auth/login` | POS | Log masuk | -| `/api/auth/logout` | POS | Log keluar | -| `/api/settings/require-login` | DAPATKAN/LETAK | Togol log masuk diperlukan | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Pengurusan Pembekal +### Provider Management -| Titik akhir | Kaedah | Penerangan | -| ---------------------------- | -------------------- | --------------------------- | -| `/api/providers` | DAPATKAN/POS | Senaraikan / buat pembekal | -| `/api/providers/[id]` | DAPATKAN/LETAK/PADAM | Urus pembekal | -| `/api/providers/[id]/test` | POS | Sambungan pembekal ujian | -| `/api/providers/[id]/models` | DAPATKAN | Senaraikan model pembekal | -| `/api/providers/validate` | POS | Sahkan konfigurasi pembekal | -| `/api/provider-nodes*` | Pelbagai | Pengurusan nod pembekal | -| `/api/provider-models` | DAPATKAN/POST/PADAM | Model tersuai | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Aliran OAuth +### OAuth Flows -| Titik akhir | Kaedah | Penerangan | -| -------------------------------- | -------- | --------------------- | -| `/api/oauth/[provider]/[action]` | Pelbagai | OAuth khusus pembekal | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Penghalaan & Konfigurasi +### Routing & Config -| Titik akhir | Kaedah | Penerangan | -| --------------------- | ------------ | ------------------------------------- | -| `/api/models/alias` | DAPATKAN/POS | Alias ​​model | -| `/api/models/catalog` | DAPATKAN | Semua model mengikut pembekal + jenis | -| `/api/combos*` | Pelbagai | Pengurusan kombo | -| `/api/keys*` | Pelbagai | Pengurusan kunci API | -| `/api/pricing` | DAPATKAN | Harga model | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Penggunaan & Analitis +### Usage & Analytics -| Titik akhir | Kaedah | Penerangan | -| --------------------------- | -------- | --------------------------- | -| `/api/usage/history` | DAPATKAN | Sejarah penggunaan | -| `/api/usage/logs` | DAPATKAN | Log penggunaan | -| `/api/usage/request-logs` | DAPATKAN | Log peringkat permintaan | -| `/api/usage/[connectionId]` | DAPATKAN | Penggunaan setiap sambungan | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Tetapan +### Settings -| Titik akhir | Kaedah | Penerangan | -| ------------------------------- | -------------- | ------------------------------------- | -| `/api/settings` | DAPATKAN/LETAK | Tetapan umum | -| `/api/settings/proxy` | DAPATKAN/LETAK | Konfigurasi proksi rangkaian | -| `/api/settings/proxy/test` | POS | Uji sambungan proksi | -| `/api/settings/ip-filter` | DAPATKAN/LETAK | Senarai dibenarkan/senarai sekatan IP | -| `/api/settings/thinking-budget` | DAPATKAN/LETAK | Belanjawan token penaakulan | -| `/api/settings/system-prompt` | DAPATKAN/LETAK | Gesaan sistem global | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Pemantauan +### Monitoring -| Titik akhir | Kaedah | Penerangan | -| ------------------------ | -------------- | --------------------------- | -| `/api/sessions` | DAPATKAN | Penjejakan sesi aktif | -| `/api/rate-limits` | DAPATKAN | Had kadar setiap akaun | -| `/api/monitoring/health` | DAPATKAN | Pemeriksaan kesihatan | -| `/api/cache` | DAPATKAN/PADAM | Statistik cache / kosongkan | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Sandaran & Eksport/Import +### Backup & Export/Import -| Titik akhir | Kaedah | Penerangan | -| --------------------------- | -------- | -------------------------------------------------------- | -| `/api/db-backups` | DAPATKAN | Senaraikan sandaran yang tersedia | -| `/api/db-backups` | LETAK | Buat sandaran manual | -| `/api/db-backups` | POS | Pulihkan daripada sandaran khusus | -| `/api/db-backups/export` | DAPATKAN | Muat turun pangkalan data sebagai fail .sqlite | -| `/api/db-backups/import` | POS | Muat naik fail .sqlite untuk menggantikan pangkalan data | -| `/api/db-backups/exportAll` | DAPATKAN | Muat turun sandaran penuh sebagai arkib .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Penyegerakan Awan +### Cloud Sync -| Titik akhir | Kaedah | Penerangan | -| ---------------------- | -------- | ------------------------- | -| `/api/sync/cloud` | Pelbagai | Operasi penyegerakan awan | -| `/api/sync/initialize` | POS | Mulakan penyegerakan | -| `/api/cloud/*` | Pelbagai | Pengurusan awan | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Alat CLI +### CLI Tools -| Titik akhir | Kaedah | Penerangan | -| ---------------------------------- | -------- | ---------------------- | -| `/api/cli-tools/claude-settings` | DAPATKAN | Status CLI Claude | -| `/api/cli-tools/codex-settings` | DAPATKAN | Status Codex CLI | -| `/api/cli-tools/droid-settings` | DAPATKAN | Status Droid CLI | -| `/api/cli-tools/openclaw-settings` | DAPATKAN | Status OpenClaw CLI | -| `/api/cli-tools/runtime/[toolId]` | DAPATKAN | Masa jalan CLI generik | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Respons CLI termasuk: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Had Ketahanan & Kadar +### ACP Agents -| Titik akhir | Kaedah | Penerangan | -| ----------------------- | -------------- | ------------------------------------ | -| `/api/resilience` | DAPATKAN/LETAK | Dapatkan/kemas kini profil ketahanan | -| `/api/resilience/reset` | POS | Tetapkan semula pemutus litar | -| `/api/rate-limits` | DAPATKAN | Status had kadar setiap akaun | -| `/api/rate-limit` | DAPATKAN | Konfigurasi had kadar global | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | ### Evals -| Titik akhir | Kaedah | Penerangan | -| ------------ | ------------ | ------------------------------------------ | -| `/api/evals` | DAPATKAN/POS | Senaraikan suite eval / penilaian jalankan | +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -### Dasar +### Policies -| Titik akhir | Kaedah | Penerangan | -| --------------- | ------------------- | --------------------- | -| `/api/policies` | DAPATKAN/POST/PADAM | Urus dasar penghalaan | +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -### Pematuhan +### Compliance -| Titik akhir | Kaedah | Penerangan | -| --------------------------- | -------- | -------------------------------- | -| `/api/compliance/audit-log` | DAPATKAN | Log audit pematuhan (N terakhir) | +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### v1beta (Serasi Gemini) +### v1beta (Gemini-Compatible) -| Titik akhir | Kaedah | Penerangan | -| -------------------------- | -------- | ------------------------------------ | -| `/v1beta/models` | DAPATKAN | Senaraikan model dalam format Gemini | -| `/v1beta/models/{...path}` | POS | Gemini `generateContent` titik akhir | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -Titik akhir ini mencerminkan format API Gemini untuk pelanggan yang mengharapkan keserasian SDK Gemini asli. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. -### API Dalaman / Sistem +### Internal / System APIs -| Titik akhir | Kaedah | Penerangan | -| --------------- | -------- | ------------------------------------------------------------ | -| `/api/init` | DAPATKAN | Semakan permulaan aplikasi (digunakan pada larian pertama) | -| `/api/tags` | DAPATKAN | Tag model yang serasi dengan Ollama (untuk pelanggan Ollama) | -| `/api/restart` | POS | Pencetus pelayan anggun mulakan semula | -| `/api/shutdown` | POS | Cetuskan penutupan pelayan yang anggun | +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | -> **Nota:** Titik akhir ini digunakan secara dalaman oleh sistem atau untuk keserasian pelanggan Ollama. Mereka biasanya tidak dipanggil oleh pengguna akhir. +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Transkripsi Audio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transkripsikan fail audio menggunakan Deepgram atau AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Permintaan:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Jawapan:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Pembekal yang disokong:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Format yang disokong:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Keserasian Ollama +## Ollama Compatibility -Untuk pelanggan yang menggunakan format API Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Permintaan diterjemahkan secara automatik antara Ollama dan format dalaman. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetri +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Jawapan:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Belanjawan +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Ketersediaan Model +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Pemprosesan Permintaan +## Request Processing -1. Pelanggan menghantar permintaan kepada `/v1/*` -2. Pengendali laluan memanggil `handleChat`, `handleEmbedding`, `handleAudioTranscription` atau `handleImageGeneration` -3. Model telah diselesaikan (pembekal langsung/model atau alias/kombo) -4. Bukti kelayakan dipilih daripada DB tempatan dengan penapisan ketersediaan akaun -5. Untuk sembang: `handleChatCore` — pengesanan format, terjemahan, semakan cache, semakan idempotensi -6. Pelaksana pembekal menghantar permintaan huluan -7. Respons diterjemahkan kembali kepada format pelanggan (sembang) atau dikembalikan seperti sedia ada (benam/imej/audio) -8. Penggunaan / pembalakan direkodkan -9. Fallback terpakai pada ralat mengikut peraturan kombo +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Rujukan seni bina penuh: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Pengesahan +## Authentication -- Laluan papan pemuka (`/dashboard/*`) gunakan kuki `auth_token` -- Log masuk menggunakan cincang kata laluan yang disimpan; sandar kepada `INITIAL_PASSWORD` -- `requireLogin` boleh togol melalui `/api/settings/require-login` -- `/v1/*` laluan secara pilihan memerlukan kunci API Pembawa apabila `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/ms/ARCHITECTURE.md b/docs/i18n/ms/ARCHITECTURE.md index c69bebd1b5..258d62df53 100644 --- a/docs/i18n/ms/ARCHITECTURE.md +++ b/docs/i18n/ms/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Seni Bina OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Terakhir dikemas kini: 2026-02-18_ +_Last updated: 2026-03-04_ -## Ringkasan Eksekutif +## Executive Summary -OmniRoute ialah get laluan dan papan pemuka penghalaan AI tempatan yang dibina pada Next.js. -Ia menyediakan satu titik akhir serasi OpenAI (`/v1/*`) dan mengarahkan trafik merentasi berbilang penyedia huluan dengan terjemahan, sandaran, penyegaran token dan penjejakan penggunaan. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Keupayaan teras: +Core capabilities: -- Permukaan API serasi OpenAI untuk CLI/alat (28 pembekal) -- Permintaan/tindak balas terjemahan merentas format pembekal -- Model kombo mundur (jujukan berbilang model) -- Saling balik peringkat akaun (berbilang akaun setiap pembekal) -- Pengurusan sambungan pembekal kunci OAuth + API -- Membenamkan penjanaan melalui `/v1/embeddings` (6 pembekal, 9 model) -- Penjanaan imej melalui `/v1/images/generations` (4 pembekal, 9 model) -- Penghuraian teg Fikir (`...`) untuk model penaakulan -- Pembersihan tindak balas untuk keserasian OpenAI SDK yang ketat -- Normalisasi peranan (pembangun→sistem, sistem→pengguna) untuk keserasian silang penyedia -- Penukaran output berstruktur (json_schema → Gemini responseSchema) -- Kegigihan setempat untuk pembekal, kunci, alias, kombo, tetapan, harga -- Penjejakan penggunaan/kos dan pengelogan permintaan -- Penyegerakan awan pilihan untuk penyegerakan berbilang peranti/keadaan -- Senarai dibenarkan/senarai sekatan IP untuk kawalan akses API -- Pengurusan belanjawan berfikir (laluan/auto/tersuai/adaptif) -- Suntikan segera sistem global -- Penjejakan sesi dan cap jari -- Pengehadan kadar dipertingkatkan setiap akaun dengan profil khusus pembekal -- Corak pemutus litar untuk daya tahan pembekal -- Perlindungan kumpulan anti-gemuruh dengan penguncian mutex -- Cache penyahduplikasi permintaan berasaskan tandatangan -- Lapisan domain: ketersediaan model, peraturan kos, dasar sandaran, dasar sekat keluar -- Kegigihan keadaan domain (cache tulis-melalui SQLite untuk sandaran, belanjawan, sekatan, pemutus litar) -- Enjin dasar untuk penilaian permintaan terpusat (kunci → belanjawan → sandaran) -- Minta telemetri dengan pengagregatan kependaman p50/p95/p99 -- ID Korelasi (X-Request-Id) untuk pengesanan hujung ke hujung -- Pengelogan audit pematuhan dengan memilih keluar setiap kunci API -- Rangka kerja Eval untuk jaminan kualiti LLM -- Papan pemuka UI Ketahanan dengan status pemutus litar masa nyata -- Pembekal OAuth modular (12 modul individu di bawah `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Model masa jalan utama: +Primary runtime model: -- Laluan apl Next.js di bawah `src/app/api/*` melaksanakan kedua-dua API papan pemuka dan API keserasian -- SSE kongsi/tera laluan dalam `src/sse/*` + `open-sse/*` mengendalikan pelaksanaan pembekal, terjemahan, penstriman, sandaran dan penggunaan +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Skop dan Sempadan +## Scope and Boundaries -### Dalam Skop +### In Scope -- Masa jalan gerbang tempatan -- API pengurusan papan pemuka -- Pengesahan pembekal dan penyegaran token -- Minta terjemahan dan penstriman SSE -- Keadaan setempat + kegigihan penggunaan -- Orkestrasi penyegerakan awan pilihan +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Di Luar Skop +### Out of Scope -- Pelaksanaan perkhidmatan awan di belakang `NEXT_PUBLIC_CLOUD_URL` -- Pembekal SLA/pesawat kawalan di luar proses tempatan -- Perduaan CLI luaran sendiri (Claude CLI, Codex CLI, dll.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Konteks Sistem Aras Tinggi +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Komponen Masa Jalan Teras +## Core Runtime Components -## 1) API dan Lapisan Penghalaan (Laluan Apl Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Direktori utama: +Main directories: -- `src/app/api/v1/*` dan `src/app/api/v1beta/*` untuk API keserasian -- `src/app/api/*` untuk API pengurusan/konfigurasi -- Seterusnya menulis semula dalam peta `next.config.mjs` `/v1/*` kepada `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Laluan keserasian penting: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — termasuk model tersuai dengan `custom: true` -- `src/app/api/v1/embeddings/route.ts` — penjanaan benam (6 pembekal) -- `src/app/api/v1/images/generations/route.ts` — penjanaan imej (4+ penyedia termasuk Antigraviti/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — sembang khusus bagi setiap pembekal -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — benam setiap pembekal khusus -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — imej setiap pembekal khusus +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Domain pengurusan: +Management domains: -- Pengesahan/tetapan: `src/app/api/auth/*`, `src/app/api/settings/*` -- Pembekal/sambungan: `src/app/api/providers*` -- Nod pembekal: `src/app/api/provider-nodes*` -- Model tersuai: `src/app/api/provider-models` (DAPAT/POS/PADAM) -- Katalog model: `src/app/api/models/catalog` (GET) -- Konfigurasi proksi: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Kunci/alias/kombo/harga: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Penggunaan: `src/app/api/usage/*` -- Penyegerakan/awan: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Pembantu perkakas CLI: `src/app/api/cli-tools/*` -- Penapis IP: `src/app/api/settings/ip-filter` (GET/PUT) -- Belanjawan berfikir: `src/app/api/settings/thinking-budget` (GET/PUT) -- Gesaan sistem: `src/app/api/settings/system-prompt` (GET/PUT) -- Sesi: `src/app/api/sessions` (GET) -- Had kadar: `src/app/api/rate-limits` (GET) -- Ketahanan: `src/app/api/resilience` (GET/PATCH) — profil pembekal, pemutus litar, keadaan had kadar -- Tetapan semula daya tahan: `src/app/api/resilience/reset` (POST) — set semula pemutus + cooldown -- Statistik cache: `src/app/api/cache/stats` (DAPAT/DELETE) -- Ketersediaan model: `src/app/api/models/availability` (GET/POST) -- Telemetri: `src/app/api/telemetry/summary` (GET) -- Belanjawan: `src/app/api/usage/budget` (DAPAT/POS) -- Rantaian mundur: `src/app/api/fallback/chains` (DAPAT/POST/PADAM) -- Audit pematuhan: `src/app/api/compliance/audit-log` (GET) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) - Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Dasar: `src/app/api/policies` (DAPAT/POS) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Teras Terjemahan +## 2) SSE + Translation Core -Modul aliran utama: +Main flow modules: -- Kemasukan: `src/sse/handlers/chat.ts` -- Orkestrasi teras: `open-sse/handlers/chatCore.ts` -- Penyesuai pelaksanaan pembekal: `open-sse/executors/*` -- Konfigurasi pengesanan format/pembekal: `open-sse/services/provider.ts` -- Penghuraian/penyelesaian model: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Logik sandaran akaun: `open-sse/services/accountFallback.ts` -- Pendaftaran terjemahan: `open-sse/translator/index.ts` -- Transformasi strim: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Pengekstrakan/penormalan penggunaan: `open-sse/utils/usageTracking.ts` -- Penghurai teg Fikir: `open-sse/utils/thinkTagParser.ts` -- Pengendali benam: `open-sse/handlers/embeddings.ts` -- Membenamkan pendaftaran pembekal: `open-sse/config/embeddingRegistry.ts` -- Pengendali penjanaan imej: `open-sse/handlers/imageGeneration.ts` -- Pendaftaran pembekal imej: `open-sse/config/imageRegistry.ts` -- Pembersihan tindak balas: `open-sse/handlers/responseSanitizer.ts` -- Normalisasi peranan: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Perkhidmatan (logik perniagaan): +Services (business logic): -- Pemilihan/pemarkahan akaun: `open-sse/services/accountSelector.ts` -- Pengurusan kitaran hayat konteks: `open-sse/services/contextManager.ts` -- Penguatkuasaan penapis IP: `open-sse/services/ipFilter.ts` -- Penjejakan sesi: `open-sse/services/sessionManager.ts` -- Minta penduaan: `open-sse/services/signatureCache.ts` -- Suntikan gesaan sistem: `open-sse/services/systemPrompt.ts` -- Pemikiran pengurusan belanjawan: `open-sse/services/thinkingBudget.ts` -- Penghalaan model kad liar: `open-sse/services/wildcardRouter.ts` -- Pengurusan had kadar: `open-sse/services/rateLimitManager.ts` -- Pemutus litar: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Modul lapisan domain: +Domain layer modules: -- Ketersediaan model: `src/lib/domain/modelAvailability.ts` -- Peraturan/belanjawan kos: `src/lib/domain/costRules.ts` -- Dasar mundur: `src/lib/domain/fallbackPolicy.ts` -- Penyelesai kombo: `src/lib/domain/comboResolver.ts` -- Dasar penguncian: `src/lib/domain/lockoutPolicy.ts` -- Enjin dasar: `src/domain/policyEngine.ts` — kunci keluar berpusat → belanjawan → penilaian mundur -- Katalog kod ralat: `src/lib/domain/errorCodes.ts` -- ID Permintaan: `src/lib/domain/requestId.ts` -- Ambil tamat masa: `src/lib/domain/fetchTimeout.ts` -- Permintaan telemetri: `src/lib/domain/requestTelemetry.ts` -- Pematuhan/audit: `src/lib/domain/compliance/index.ts` -- Pelari eval: `src/lib/domain/evalRunner.ts` -- Kegigihan keadaan domain: `src/lib/db/domainState.ts` — SQLite CRUD untuk rantaian sandaran, belanjawan, sejarah kos, keadaan sekat keluar, pemutus litar +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Modul pembekal OAuth (12 fail individu di bawah `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Indeks pendaftaran: `src/lib/oauth/providers/index.ts` -- Pembekal individu: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Pembalut nipis: `src/lib/oauth/providers.ts` — eksport semula daripada modul individu +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Lapisan Kegigihan +## 3) Persistence Layer -DB keadaan utama: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- fail: `${DATA_DIR}/db.json` (atau `$XDG_CONFIG_HOME/omniroute/db.json` apabila ditetapkan, jika tidak `~/.omniroute/db.json`) -- entiti: providerConnections, providerNodes, modelAliases, combo, apiKeys, tetapan, harga, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Penggunaan DB: +Usage persistence: -- `src/lib/usageDb.ts` -- fail: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- mengikut dasar direktori asas yang sama seperti `localDb` (`DATA_DIR`, kemudian `XDG_CONFIG_HOME/omniroute` apabila ditetapkan) -- diuraikan kepada sub-modul terfokus: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -DB Keadaan Domain (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — Operasi CRUD untuk keadaan domain -- Jadual (dicipta dalam `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Corak cache tulis-lalu: Peta dalam ingatan adalah berwibawa pada masa jalan; mutasi ditulis serentak kepada SQLite; keadaan dipulihkan daripada DB pada permulaan sejuk +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start ## 4) Auth + Security Surfaces -- Pengesahan kuki papan pemuka: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Penjanaan/pengesahan kunci API: `src/shared/utils/apiKey.ts` -- Rahsia pembekal kekal dalam entri `providerConnections` -- Sokongan proksi keluar melalui `open-sse/utils/proxyFetch.ts` (env vars) dan `open-sse/utils/networkProxy.ts` (boleh dikonfigurasikan setiap pembekal atau global) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Penyegerakan Awan +## 5) Cloud Sync -- Penjadual init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Tugasan berkala: `src/shared/services/cloudSyncScheduler.ts` -- Laluan kawalan: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Permintaan Kitaran Hayat (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Kombo + Aliran Saling Balik Akaun +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Keputusan sandaran didorong oleh `open-sse/services/accountFallback.ts` menggunakan kod status dan heuristik mesej ralat. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth Onboarding dan Kitaran Hayat Penyegaran Token +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Muat semula semasa trafik langsung dilaksanakan di dalam `open-sse/handlers/chatCore.ts` melalui pelaksana `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Kitaran Hayat Penyegerakan Awan (Dayakan / Segerakkan / Lumpuhkan) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Penyegerakan berkala dicetuskan oleh `CloudSyncScheduler` apabila awan didayakan. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Model Data dan Peta Storan +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Fail storan fizikal: +Physical storage files: -- keadaan utama: `${DATA_DIR}/db.json` (atau `$XDG_CONFIG_HOME/omniroute/db.json` apabila ditetapkan, jika tidak `~/.omniroute/db.json`) -- statistik penggunaan: `${DATA_DIR}/usage.json` -- permintaan baris log: `${DATA_DIR}/log.txt` -- pilihan penterjemah/permintaan sesi nyahpepijat: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topologi Penerapan +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Pemetaan Modul (Keputusan-Kritis) +## Module Mapping (Decision-Critical) -### Laluan dan Modul API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API keserasian -- `src/app/api/v1/providers/[provider]/*`: laluan khusus setiap pembekal (sembang, benam, imej) -- `src/app/api/providers*`: penyedia CRUD, pengesahan, ujian -- `src/app/api/provider-nodes*`: pengurusan nod serasi tersuai -- `src/app/api/provider-models`: pengurusan model tersuai (CRUD) -- `src/app/api/models/catalog`: API katalog model penuh (semua jenis dikumpulkan mengikut pembekal) -- `src/app/api/oauth/*`: Aliran OAuth/kod peranti -- `src/app/api/keys*`: kitaran hayat kunci API tempatan -- `src/app/api/models/alias`: pengurusan alias -- `src/app/api/combos*`: pengurusan kombo sandaran -- `src/app/api/pricing`: penentuan harga untuk pengiraan kos -- `src/app/api/settings/proxy`: konfigurasi proksi (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: ujian sambungan proksi keluar (POST) -- `src/app/api/usage/*`: API penggunaan dan log -- `src/app/api/sync/*` + `src/app/api/cloud/*`: penyegerakan awan dan pembantu yang menghadap awan -- `src/app/api/cli-tools/*`: penulis/pemeriksa konfigurasi CLI tempatan -- `src/app/api/settings/ip-filter`: Senarai dibenarkan/senarai sekat IP (GET/PUT) -- `src/app/api/settings/thinking-budget`: konfigurasi belanjawan token pemikiran (GET/PUT) -- `src/app/api/settings/system-prompt`: gesaan sistem global (GET/PUT) -- `src/app/api/sessions`: penyenaraian sesi aktif (GET) -- `src/app/api/rate-limits`: status had kadar setiap akaun (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Penghalaan dan Teras Pelaksanaan +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: menghuraikan permintaan, pengendalian kombo, gelung pemilihan akaun -- `open-sse/handlers/chatCore.ts`: terjemahan, penghantaran pelaksana, cuba semula/segar semula pengendalian, persediaan strim -- `open-sse/executors/*`: rangkaian khusus pembekal dan tingkah laku format +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Pendaftar Terjemahan dan Penukar Format +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: pendaftaran penterjemah dan orkestrasi -- Minta penterjemah: `open-sse/translator/request/*` -- Penterjemah respons: `open-sse/translator/response/*` -- Pemalar format: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Kegigihan +### Persistence -- `src/lib/localDb.ts`: konfigurasi/keadaan berterusan -- `src/lib/usageDb.ts`: sejarah penggunaan dan log permintaan bergulir +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Liputan Pelaksana Penyedia (Corak Strategi) +## Provider Executor Coverage (Strategy Pattern) -Setiap pembekal mempunyai pelaksana khusus yang memanjangkan `BaseExecutor` (dalam `open-sse/executors/base.ts`), yang menyediakan pembinaan URL, pembinaan pengepala, cuba semula dengan pengunduran eksponen, cangkuk penyegaran semula kelayakan dan kaedah orkestra `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Pelaksana | Pembekal | Pengendalian Khas | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | URL dinamik/konfigurasi pengepala bagi setiap pembekal | -| `AntigravityExecutor` | Antigraviti Google | ID projek/sesi tersuai, Cuba Semula-Selepas menghuraikan | -| `CodexExecutor` | OpenAI Codex | Menyuntik arahan sistem, memaksa usaha penaakulan | -| `CursorExecutor` | IDE kursor | Protokol ConnectRPC, pengekodan Protobuf, tandatangan permintaan melalui checksum | -| `GithubExecutor` | GitHub Copilot | Penyegaran token salinan, pengepala meniru VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Format binari AWS EventStream → penukaran SSE | -| `GeminiCLIExecutor` | Gemini CLI | Kitaran muat semula token Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Semua pembekal lain (termasuk nod serasi tersuai) menggunakan `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matriks Keserasian Pembekal +## Provider Compatibility Matrix -| Pembekal | Format | Pengesahan | Strim | Bukan Strim | Token Refresh | API Penggunaan | -| ---------------- | -------------- | --------------------- | ---------------- | ----------- | ------------- | -------------------- | -| Claude | claude | Kunci API / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin sahaja | -| Gemini | gemini | Kunci API / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Antigraviti | antigraviti | OAuth | ✅ | ✅ | ✅ | ✅ API kuota penuh | -| OpenAI | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-respons | OAuth | ✅ terpaksa | ❌ | ✅ | ✅ Had kadar | -| GitHub Copilot | openai | OAuth + Token Copilot | ✅ | ✅ | ✅ | ✅ Gambar kuota | -| Kursor | kursor | Jumlah semak tersuai | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Had penggunaan | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Setiap permintaan | -| iFlow | openai | OAuth (Asas) | ✅ | ✅ | ✅ | ⚠️ Setiap permintaan | -| OpenRouter | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | Kunci API | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Kebingungan | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Bersama AI | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Bunga Api AI | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Serebral | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| Cohere | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Liputan Terjemahan Format +## Format Translation Coverage -Format sumber yang dikesan termasuk: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Format sasaran termasuk: +Target formats include: -- Sembang/Respons OpenAI +- OpenAI chat/Responses - Claude -- Sampul surat Gemini/Gemini-CLI/Antigraviti +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Kursor +- Cursor -Terjemahan menggunakan **OpenAI sebagai format hab** — semua penukaran melalui OpenAI sebagai perantaraan: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Terjemahan dipilih secara dinamik berdasarkan bentuk muatan sumber dan format sasaran pembekal. +Translations are selected dynamically based on source payload shape and provider target format. -Lapisan pemprosesan tambahan dalam saluran paip terjemahan: +Additional processing layers in the translation pipeline: -- **Pembersihan respons** — Menghapuskan medan bukan standard daripada respons format OpenAI (kedua-dua penstriman dan bukan penstriman) untuk memastikan pematuhan SDK yang ketat -- **Penormalan peranan** — Menukar `developer` → `system` untuk sasaran bukan OpenAI; menggabungkan `system` → `user` untuk model yang menolak peranan sistem (GLM, ERNIE) -- **Fikirkan pengekstrakan teg** — Menghuraikan `...` blok daripada kandungan ke dalam medan `reasoning_content` -- **Output berstruktur** — Menukar OpenAI `response_format.json_schema` kepada `responseMimeType` + `responseSchema` Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Titik Akhir API Disokong +## Supported API Endpoints -| Titik akhir | Format | Pengendali | -| -------------------------------------------------- | -------------------- | --------------------------------------------------- | -| `POST /v1/chat/completions` | Sembang OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Mesej Claude | Pengendali yang sama (dikesan secara automatik) | -| `POST /v1/responses` | Respons OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Pembenaman OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Penyenaraian model | Laluan API | -| `POST /v1/images/generations` | Imej OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Penyenaraian model | Laluan API | -| `POST /v1/providers/{provider}/chat/completions` | Sembang OpenAI | Khas bagi setiap pembekal dengan pengesahan model | -| `POST /v1/providers/{provider}/embeddings` | Pembenaman OpenAI | Khusus bagi setiap pembekal dengan pengesahan model | -| `POST /v1/providers/{provider}/images/generations` | Imej OpenAI | Khusus bagi setiap pembekal dengan pengesahan model | -| `POST /v1/messages/count_tokens` | Kiraan Token Claude | Laluan API | -| `GET /v1/models` | Senarai Model OpenAI | Laluan API (sembang + benam + imej + model tersuai) | -| `GET /api/models/catalog` | Katalog | Semua model dikumpulkan mengikut pembekal + jenis | -| `POST /v1beta/models/*:streamGenerateContent` | Gemini asli | Laluan API | -| `GET/PUT/DELETE /api/settings/proxy` | Konfigurasi Proksi | Konfigurasi proksi rangkaian | -| `POST /api/settings/proxy/test` | Kesambungan Proksi | Titik akhir ujian kesihatan/ketersambungan proksi | -| `GET/POST/DELETE /api/provider-models` | Model Tersuai | Pengurusan model tersuai setiap pembekal | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Pengendali Pintasan +## Bypass Handler -Pengendali pintasan (`open-sse/utils/bypassHandler.ts`) memintas permintaan "buang" yang diketahui daripada Claude CLI — ping pemanasan, pengekstrakan tajuk dan kiraan token — dan mengembalikan **tindak balas palsu** tanpa menggunakan token penyedia huluan. Ini dicetuskan hanya apabila `User-Agent` mengandungi `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Permintaan Talian Logger +## Request Logger Pipeline -Logger permintaan (`open-sse/utils/requestLogger.ts`) menyediakan saluran paip pengelogan nyahpepijat 7 peringkat, dilumpuhkan secara lalai, didayakan melalui `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Fail ditulis kepada `/logs//` untuk setiap sesi permintaan. +Files are written to `/logs//` for each request session. -## Mod Kegagalan dan Ketahanan +## Failure Modes and Resilience -## 1) Ketersediaan Akaun/Pembekal +## 1) Account/Provider Availability -- cooldown akaun pembekal pada ralat sementara/kadar/auth -- sandaran akaun sebelum permintaan gagal -- sandaran model kombo apabila model semasa/laluan pembekal telah habis +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Tamat Tempoh Token +## 2) Token Expiry -- prasemak dan muat semula dengan mencuba semula untuk pembekal yang boleh dimuat semula -- 401/403 cuba semula selepas percubaan muat semula dalam laluan teras +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Keselamatan Aliran +## 3) Stream Safety -- pengawal strim sedar putus sambungan -- strim terjemahan dengan siram hujung strim dan pengendalian `[DONE]` -- sandaran anggaran penggunaan apabila metadata penggunaan pembekal tiada +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Kemerosotan Penyegerakan Awan +## 4) Cloud Sync Degradation -- ralat penyegerakan muncul tetapi masa jalan tempatan diteruskan -- penjadual mempunyai logik yang mampu mencuba semula, tetapi pelaksanaan berkala pada masa ini memanggil penyegerakan percubaan tunggal secara lalai +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integriti Data +## 5) Data Integrity -- Penghijrahan/pembaikan bentuk DB untuk kunci yang hilang -- perlindungan semula JSON yang rosak untuk localDb dan usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Kebolehlihatan dan Isyarat Operasi +## Observability and Operational Signals -Sumber keterlihatan masa jalan: +Runtime visibility sources: -- log konsol daripada `src/sse/utils/logger.ts` -- agregat penggunaan setiap permintaan dalam `usage.json` -- log masuk status permintaan teks `log.txt` -- log permintaan/terjemahan dalam pilihan di bawah `logs/` apabila `ENABLE_REQUEST_LOGS=true` -- titik akhir penggunaan papan pemuka (`/api/usage/*`) untuk penggunaan UI +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Sempadan Sensitif Keselamatan +## Security-Sensitive Boundaries -- Rahsia JWT (`JWT_SECRET`) menjamin pengesahan/penandatanganan kuki sesi papan pemuka -- Saling balik kata laluan awal (`INITIAL_PASSWORD`, lalai `123456`) mesti ditindih dalam penggunaan sebenar -- Rahsia HMAC kunci API (`API_KEY_SECRET`) menjamin format kunci API tempatan yang dijana -- Rahsia pembekal (kunci/token API) dikekalkan dalam DB tempatan dan harus dilindungi pada peringkat sistem fail -- Titik akhir penyegerakan awan bergantung pada pengesahan kunci API + semantik id mesin +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Persekitaran dan Matriks Masa Jalan +## Environment and Runtime Matrix -Pembolehubah persekitaran digunakan secara aktif oleh kod: +Environment variables actively used by code: -- Apl/auth: `JWT_SECRET`, `INITIAL_PASSWORD` -- Storan: `DATA_DIR` -- Tingkah laku nod yang serasi: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Penggantian asas storan pilihan (Linux/macOS apabila `DATA_DIR` dinyahset): `XDG_CONFIG_HOME` -- Pencincangan keselamatan: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Pembalakan: `ENABLE_REQUEST_LOGS` -- URL penyegerakan/awan: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Proksi keluar: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` dan varian huruf kecil -- Bendera ciri SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Pembantu platform/masa jalanan (bukan konfigurasi khusus apl): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Nota Seni Bina Terkenal +## Known Architectural Notes -1. `usageDb` dan `localDb` kini berkongsi dasar direktori asas yang sama (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) dengan pemindahan fail lama. -2. `/api/v1/route.ts` mengembalikan senarai model statik dan bukan sumber model utama yang digunakan oleh `/v1/models`. -3. Permintaan logger menulis tajuk/badan penuh apabila didayakan; anggap direktori log sebagai sensitif. -4. Gelagat awan bergantung pada `NEXT_PUBLIC_BASE_URL` dan kebolehcapaian titik akhir awan yang betul. -5. Direktori `open-sse/` diterbitkan sebagai `@omniroute/open-sse` **pakej ruang kerja npm**. Kod sumber mengimportnya melalui `@omniroute/open-sse/...` (diselesaikan oleh Next.js `transpilePackages`). Laluan fail dalam dokumen ini masih menggunakan nama direktori `open-sse/` untuk konsistensi. -6. Carta dalam papan pemuka menggunakan **Recharts** (berasaskan SVG) untuk visualisasi analitik interaktif yang boleh diakses (carta bar penggunaan model, jadual pecahan pembekal dengan kadar kejayaan). -7. Ujian E2E menggunakan **Playwright** (`tests/e2e/`), dijalankan melalui `npm run test:e2e`. Ujian unit menggunakan **Node.js test runner** (`tests/unit/`), dijalankan melalui `npm run test:plan3`. Kod sumber di bawah `src/` ialah **TypeScript** (`.ts`/`.tsx`); ruang kerja `open-sse/` kekal sebagai JavaScript (`.js`). -8. Halaman tetapan disusun dalam 5 tab: Keselamatan, Penghalaan (6 strategi global: isikan dahulu, round-robin, p2c, rawak, paling kurang digunakan, dioptimumkan kos), Ketahanan (had kadar boleh diedit, pemutus litar, dasar), AI (belanjawan berfikir, gesaan sistem, cache segera), Lanjutan (proksi). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Senarai Semak Pengesahan Operasi +## Operational Verification Checklist -- Bina daripada sumber: `npm run build` -- Bina imej Docker: `docker build -t omniroute .` -- Mulakan perkhidmatan dan sahkan: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- URL asas sasaran CLI hendaklah `http://:20128/v1` apabila `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ms/CODEBASE_DOCUMENTATION.md b/docs/i18n/ms/CODEBASE_DOCUMENTATION.md index 2db7179e24..303880c198 100644 --- a/docs/i18n/ms/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/ms/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Dokumentasi Pangkalan Kod +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Panduan komprehensif dan mesra pemula kepada penghala proksi AI **omniroute** berbilang pembekal. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Apakah itu omniroute? +## 1. What Is omniroute? -omniroute ialah **penghala proksi** yang terletak di antara klien AI (Claude CLI, Codex, Cursor IDE, dll.) dan penyedia AI (Anthropic, Google, OpenAI, AWS, GitHub, dsb.). Ia menyelesaikan satu masalah besar: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Pelanggan AI yang berbeza bercakap "bahasa" yang berbeza (format API), dan pembekal AI yang berbeza juga mengharapkan "bahasa" yang berbeza.** omniroute menterjemah antara mereka secara automatik. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Anggaplah ia seperti penterjemah universal di Pertubuhan Bangsa-Bangsa Bersatu — mana-mana perwakilan boleh bercakap apa-apa bahasa, dan penterjemah menukarnya untuk mana-mana perwakilan lain. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Gambaran Keseluruhan Seni Bina +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Prinsip Teras: Terjemahan Hub-and-Spoke +### Core Principle: Hub-and-Spoke Translation -Semua terjemahan format melalui **format OpenAI sebagai hab**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Ini bermakna anda hanya memerlukan **N penterjemah** (satu setiap format) dan bukannya **N²** (setiap pasangan). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Struktur Projek +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Pecahan Modul demi Modul +## 4. Module-by-Module Breakdown -### 4.1 Konfigurasi (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**Sumber tunggal kebenaran** untuk semua konfigurasi pembekal. +The **single source of truth** for all provider configuration. -| Fail | Tujuan | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` objek dengan URL asas, bukti kelayakan OAuth (lalai), pengepala dan gesaan sistem lalai untuk setiap pembekal. Juga mentakrifkan `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` dan `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Memuatkan bukti kelayakan luaran daripada `data/provider-credentials.json` dan menggabungkannya pada lalai berkod keras dalam `PROVIDERS`. Menyimpan rahsia di luar kawalan sumber sambil mengekalkan keserasian ke belakang. | -| `providerModels.ts` | Pendaftaran model pusat: alias penyedia peta → ID model. Berfungsi seperti `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Arahan sistem disuntik ke dalam permintaan Codex (kekangan pengeditan, peraturan kotak pasir, dasar kelulusan). | -| `defaultThinkingSignature.ts` | Tanda tangan "berfikir" lalai untuk model Claude dan Gemini. | -| `ollamaModels.ts` | Takrif skema untuk model Ollama tempatan (nama, saiz, keluarga, pengkuantitian). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Aliran Pemuatan Kredensial +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Pelaksana (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Pelaksana merangkum **logik khusus pembekal** menggunakan **Corak Strategi**. Setiap pelaksana mengatasi kaedah asas seperti yang diperlukan. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Pelaksana | Pembekal | Pengkhususan Utama | -| ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Asas abstrak: Pembinaan URL, pengepala, cuba semula logik, penyegaran semula kelayakan | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Muat semula token OAuth generik untuk pembekal standard | -| `antigravity.ts` | Kod Awan Google | Penjanaan ID projek/sesi, sandaran berbilang URL, cuba semula tersuai menghuraikan daripada mesej ralat ("set semula selepas 2h7m23s") | -| `cursor.ts` | IDE kursor | **Paling kompleks**: Pengesahan checksum SHA-256, pengekodan permintaan Protobuf, Perduaan EventStream → Penghuraian respons SSE | -| `codex.ts` | OpenAI Codex | Menyuntik arahan sistem, mengurus tahap pemikiran, mengalih keluar parameter yang tidak disokong | -| `gemini-cli.ts` | Google Gemini CLI | Pembinaan URL tersuai (`streamGenerateContent`), muat semula token Google OAuth | -| `github.ts` | GitHub Copilot | Sistem token dwi (GitHub OAuth + Copilot token), pengepala VSCode meniru | -| `kiro.ts` | AWS CodeWhisperer | Penghuraian binari AWS EventStream, bingkai acara AMZN, anggaran token | -| `index.ts` | — | Kilang: nama pembekal peta → kelas pelaksana, dengan sandaran lalai | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Pengendali (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**Lapisan orkestrasi** — menyelaras terjemahan, pelaksanaan, penstriman dan pengendalian ralat. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Fail | Tujuan | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Orkestra pusat** (~600 baris). Mengendalikan kitaran hayat permintaan yang lengkap: pengesanan format → terjemahan → penghantaran pelaksana → respons penstriman/bukan penstriman → penyegaran token → pengendalian ralat → pengelogan penggunaan. | -| `responsesHandler.ts` | Penyesuai untuk API Respons OpenAI: menukar format Respons → Selesai Sembang → menghantar kepada `chatCore` → menukar SSE kembali kepada format Respons. | -| `embeddings.ts` | Pengendali penjanaan benam: menyelesaikan model pembenaman → pembekal, menghantar kepada API pembekal, mengembalikan respons pembenaman serasi OpenAI. Menyokong 6+ pembekal. | -| `imageGeneration.ts` | Pengendali penjanaan imej: menyelesaikan model imej → pembekal, menyokong mod serasi OpenAI, imej Gemini (Antigraviti) dan sandaran (Nebius). Mengembalikan imej base64 atau URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Minta Kitaran Hayat (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Perkhidmatan (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Logik perniagaan yang menyokong pengendali dan pelaksana. +Business logic that supports the handlers and executors. -| Fail | Tujuan | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Pengesanan format** (`detectFormat`): menganalisis struktur badan permintaan untuk mengenal pasti format Claude/OpenAI/Gemini/Antigravity/Respons (termasuk `max_tokens` heuristik untuk Claude). Juga: Pembinaan URL, pembinaan pengepala, penormalan konfigurasi pemikiran. Menyokong `openai-compatible-*` dan `anthropic-compatible-*` pembekal dinamik. | -| `model.ts` | Penghuraian rentetan model (`claude/model-name` → `{provider: "claude", model: "model-name"}`), resolusi alias dengan pengesanan perlanggaran, pembersihan input (menolak aksara traversal/kawalan laluan) dan resolusi maklumat model dengan sokongan alias getter async. | -| `accountFallback.ts` | Pengendalian had kadar: pengunduran eksponen (1s → 2s → 4s → maks 2minit), pengurusan cooldown akaun, klasifikasi ralat (ralat yang mencetuskan sandaran berbanding tidak). | -| `tokenRefresh.ts` | Muat semula token OAuth untuk **setiap pembekal**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dwi-token), Kiro (AWS SSO OIDC + Social Auth). Termasuk cache penyahduplikasi janji dalam penerbangan dan cuba semula dengan pengunduran eksponen. | -| `combo.ts` | **Model kombo**: rangkaian model sandaran. Jika model A gagal dengan ralat layak sandar, cuba model B, kemudian C, dsb. Mengembalikan kod status huluan sebenar. | -| `usage.ts` | Mengambil data kuota/penggunaan daripada API pembekal (kuota Copilot GitHub, kuota model Antigraviti, had kadar Codex, pecahan penggunaan Kiro, tetapan Claude). | -| `accountSelector.ts` | Pemilihan akaun pintar dengan algoritma pemarkahan: mempertimbangkan keutamaan, status kesihatan, kedudukan round-robin dan keadaan cooldown untuk memilih akaun yang optimum bagi setiap permintaan. | -| `contextManager.ts` | Meminta pengurusan kitaran hayat konteks: mencipta dan menjejak objek konteks setiap permintaan dengan metadata (ID permintaan, cap masa, maklumat pembekal) untuk penyahpepijatan dan pengelogan. | -| `ipFilter.ts` | Kawalan capaian berasaskan IP: menyokong mod senarai dibenarkan dan senarai sekat. Mengesahkan IP klien terhadap peraturan yang dikonfigurasikan sebelum memproses permintaan API. | -| `sessionManager.ts` | Penjejakan sesi dengan cap jari pelanggan: menjejaki sesi aktif menggunakan pengecam pelanggan dicincang, memantau kiraan permintaan dan menyediakan metrik sesi. | -| `signatureCache.ts` | Minta cache penyahduplikasian berasaskan tandatangan: menghalang permintaan pendua dengan menyimpan cache tandatangan permintaan terkini dan mengembalikan respons cache untuk permintaan yang sama dalam tetingkap masa. | -| `systemPrompt.ts` | Suntikan gesaan sistem global: menambah atau menambahkan gesaan sistem yang boleh dikonfigurasikan kepada semua permintaan, dengan pengendalian keserasian setiap pembekal. | -| `thinkingBudget.ts` | Pengurusan belanjawan token penaakulan: menyokong mod laluan lalu, auto (konfigurasi pemikiran jalur), tersuai (belanjawan tetap) dan mod penyesuaian (berskala kerumitan) untuk mengawal token pemikiran/penaakulan. | -| `wildcardRouter.ts` | Penghalaan corak model kad liar: menyelesaikan corak kad bebas (cth., `*/claude-*`) kepada pasangan pembekal/model konkrit berdasarkan ketersediaan dan keutamaan. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Deduplikasi Token Refresh +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Mesin Keadaan Fallback Akaun +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Rantai Model Kombo +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Penterjemah (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**enjin terjemahan format** menggunakan sistem pemalam pendaftaran sendiri. +The **format translation engine** using a self-registering plugin system. -#### Seni bina +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Direktori | Fail | Penerangan | -| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 penterjemah | Tukar badan permintaan antara format. Setiap fail mendaftar sendiri melalui `register(from, to, fn)` semasa diimport. | -| `response/` | 7 penterjemah | Tukar ketulan respons penstriman antara format. Mengendalikan jenis acara SSE, blok pemikiran, panggilan alat. | -| `helpers/` | 6 pembantu | Utiliti dikongsi: `claudeHelper` (pengekstrak segera sistem, konfigurasi pemikiran), `geminiHelper` (pemetaan bahagian/kandungan), `openaiHelper` (penapisan format), `toolCallHelper` (penjanaan ID, suntikan tindak balas tiada), `toolCallHelper`, `toolCallHelper` | -| `index.ts` | — | Enjin terjemahan: `translateRequest()`, `translateResponse()`, pengurusan negeri, pendaftaran. | -| `formats.ts` | — | Pemalar format: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Reka Bentuk Utama: Pemalam Mendaftar Sendiri +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Util (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Fail | Tujuan | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Pembinaan tindak balas ralat (format serasi OpenAI), penghuraian ralat huluan, Pengekstrakan masa percubaan semula Antigraviti daripada mesej ralat, penstriman ralat SSE. | -| `stream.ts` | **SSE Transform Stream** — saluran paip penstriman teras. Dua mod: `TRANSLATE` (terjemahan format penuh) dan `PASSTHROUGH` (normalkan + penggunaan ekstrak). Mengendalikan penimbalan bongkah, anggaran penggunaan, penjejakan panjang kandungan. Kejadian pengekod/penyahkod setiap aliran mengelakkan keadaan dikongsi. | -| `streamHelpers.ts` | Utiliti SSE peringkat rendah: `parseSSELine` (bertoleransi ruang putih), `hasValuableContent` (menapis ketulan kosong untuk OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialisasi SSE sedar format dengan pembersihan `perf_metrics`). | -| `usageTracking.ts` | Pengekstrakan penggunaan token daripada sebarang format (Claude/OpenAI/Gemini/Responses), anggaran dengan nisbah char-per-token alat/mesej yang berasingan, penambahan penimbal (margin keselamatan 2000 token), penapisan medan khusus format, pengelogan konsol dengan warna ANSI. | -| `requestLogger.ts` | Pengelogan permintaan berasaskan fail (ikut serta melalui `ENABLE_REQUEST_LOGS=true`). Mencipta folder sesi dengan fail bernombor: `1_req_client.json` → `7_res_client.txt`. Semua I/O tidak segerak (api-dan-lupa). Topeng tajuk sensitif. | -| `bypassHandler.ts` | Memintas corak tertentu daripada Claude CLI (pengeluaran tajuk, pemanasan, kiraan) dan mengembalikan respons palsu tanpa menghubungi mana-mana pembekal. Menyokong kedua-dua penstriman dan bukan penstriman. Sengaja dihadkan kepada skop Claude CLI. | -| `networkProxy.ts` | Menyelesaikan URL proksi keluar untuk pembekal tertentu dengan keutamaan: konfigurasi khusus pembekal → konfigurasi global → pembolehubah persekitaran (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Menyokong `NO_PROXY` pengecualian. Konfigurasi cache untuk 30s. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Saluran Paip Penstriman SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Permintaan Struktur Sesi Logger +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Lapisan Aplikasi (`src/`) +### 4.7 Application Layer (`src/`) -| Direktori | Tujuan | -| ------------- | ----------------------------------------------------------------------------- | -| `src/app/` | UI Web, laluan API, perisian tengah Ekspres, pengendali panggil balik OAuth | -| `src/lib/` | Akses pangkalan data (`localDb.ts`, `usageDb.ts`), pengesahan, dikongsi | -| `src/mitm/` | Utiliti proksi man-in-the-middle untuk memintas trafik pembekal | -| `src/models/` | Takrif model pangkalan data | -| `src/shared/` | Pembalut di sekeliling fungsi open-sse (penyedia, strim, ralat, dll.) | -| `src/sse/` | Pengendali titik akhir SSE yang menghantar pustaka open-sse ke laluan Express | -| `src/store/` | Pengurusan keadaan aplikasi | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Laluan API Terkenal +#### Notable API Routes -| Laluan | Kaedah | Tujuan | -| --------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------- | -| `/api/provider-models` | DAPATKAN/POST/PADAM | CRUD untuk model tersuai setiap pembekal | -| `/api/models/catalog` | DAPATKAN | Katalog agregat semua model (sembang, benam, imej, tersuai) dikumpulkan mengikut pembekal | -| `/api/settings/proxy` | DAPATKAN/LETAK/PADAM | Konfigurasi proksi keluar hierarki (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POS | Mengesahkan sambungan proksi dan mengembalikan IP/kependaman awam | -| `/v1/providers/[provider]/chat/completions` | POS | Penyelesaian sembang khusus bagi setiap pembekal dengan pengesahan model | -| `/v1/providers/[provider]/embeddings` | POS | Pembenaman khusus bagi setiap pembekal dengan pengesahan model | -| `/v1/providers/[provider]/images/generations` | POS | Penjanaan imej setiap pembekal khusus dengan pengesahan model | -| `/api/settings/ip-filter` | DAPATKAN/LETAK | Pengurusan senarai dibenarkan/senarai sekat IP | -| `/api/settings/thinking-budget` | DAPATKAN/LETAK | Konfigurasi belanjawan token penaakulan (laluan/auto/tersuai/suai) | -| `/api/settings/system-prompt` | DAPATKAN/LETAK | Suntikan segera sistem global untuk semua permintaan | -| `/api/sessions` | DAPATKAN | Penjejakan dan metrik sesi aktif | -| `/api/rate-limits` | DAPATKAN | Status had kadar setiap akaun | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Corak Reka Bentuk Utama +## 5. Key Design Patterns -### 5.1 Terjemahan Hub-and-Spoke +### 5.1 Hub-and-Spoke Translation -Semua format diterjemahkan melalui **format OpenAI sebagai hab**. Menambah penyedia baharu hanya memerlukan penulisan **sepasang** penterjemah (ke/dari OpenAI), bukan N pasangan. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Corak Strategi Pelaksana +### 5.2 Executor Strategy Pattern -Setiap pembekal mempunyai kelas pelaksana khusus yang diwarisi daripada `BaseExecutor`. Kilang di `executors/index.ts` memilih yang betul semasa masa jalan. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Sistem Pemalam Mendaftar Sendiri +### 5.3 Self-Registering Plugin System -Modul penterjemah mendaftarkan diri mereka pada import melalui `register()`. Menambah penterjemah baharu hanyalah mencipta fail dan mengimportnya. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Pengunduran Akaun dengan Pengunduran Eksponen +### 5.4 Account Fallback with Exponential Backoff -Apabila pembekal mengembalikan 429/401/500, sistem boleh bertukar ke akaun seterusnya, menggunakan tempoh bertenang eksponen (1s → 2s → 4s → maks 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Rantai Model Kombo +### 5.5 Combo Model Chains -"Kombo" mengumpulkan berbilang rentetan `provider/model`. Jika yang pertama gagal, sandarkan kepada yang seterusnya secara automatik. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Terjemahan Penstriman Stateful +### 5.6 Stateful Streaming Translation -Terjemahan respons mengekalkan keadaan merentas bahagian SSE (penjejakan blok pemikiran, pengumpulan panggilan alat, pengindeksan blok kandungan) melalui mekanisme `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Penimbal Keselamatan Penggunaan +### 5.7 Usage Safety Buffer -Penampan 2000-token ditambahkan pada penggunaan yang dilaporkan untuk menghalang pelanggan daripada mencapai had tetingkap konteks kerana overhed daripada gesaan sistem dan terjemahan format. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Format yang Disokong +## 6. Supported Formats -| Format | Arah | Pengecam | -| ---------------------- | ---------------- | ------------------ | -| Selesai Sembang OpenAI | sumber + sasaran | `openai` | -| API Respons OpenAI | sumber + sasaran | `openai-responses` | -| Claude Anthropic | sumber + sasaran | `claude` | -| Google Gemini | sumber + sasaran | `gemini` | -| Google Gemini CLI | sasaran sahaja | `gemini-cli` | -| Antigraviti | sumber + sasaran | `antigravity` | -| AWS Kiro | sasaran sahaja | `kiro` | -| Kursor | sasaran sahaja | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Pembekal yang Disokong +## 7. Supported Providers -| Pembekal | Kaedah Pengesahan | Pelaksana | Nota Utama | -| ------------------------ | ------------------------ | ----------- | -------------------------------------------------------- | -| Claude Anthropic | Kunci API atau OAuth | Lalai | Menggunakan pengepala `x-api-key` | -| Google Gemini | Kunci API atau OAuth | Lalai | Menggunakan pengepala `x-goog-api-key` | -| Google Gemini CLI | OAuth | GeminiCLI | Menggunakan `streamGenerateContent` titik akhir | -| Antigraviti | OAuth | Antigraviti | Undur berbilang URL, penghuraian cuba semula tersuai | -| OpenAI | Kunci API | Lalai | Pengesahan Pembawa Standard | -| Codex | OAuth | Codex | Menyuntik arahan sistem, mengurus pemikiran | -| GitHub Copilot | Token OAuth + Copilot | Github | Token dwi, ​​pengepala VSCode meniru | -| Kiro (AWS) | AWS SSO OIDC atau Sosial | Kiro | Perduaan EventStream parsing | -| IDE kursor | Pengesahan semak | Kursor | Pengekodan Protobuf, jumlah semak SHA-256 | -| Qwen | OAuth | Lalai | Pengesahan standard | -| iFlow | OAuth (Asas + Pembawa) | Lalai | Pengepala dwi pengesahan | -| OpenRouter | Kunci API | Lalai | Pengesahan Pembawa Standard | -| GLM, Kimi, MiniMax | Kunci API | Lalai | Serasi Claude, gunakan `x-api-key` | -| `openai-compatible-*` | Kunci API | Lalai | Dinamik: mana-mana titik akhir serasi OpenAI | -| `anthropic-compatible-*` | Kunci API | Lalai | Dinamik: mana-mana titik akhir yang serasi dengan Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Ringkasan Aliran Data +## 8. Data Flow Summary -### Permintaan Penstriman +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Permintaan Bukan Penstriman +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Aliran Pintasan (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/ms/FEATURES.md b/docs/i18n/ms/FEATURES.md index 9128775f08..82cc73b67b 100644 --- a/docs/i18n/ms/FEATURES.md +++ b/docs/i18n/ms/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Galeri Ciri Papan Pemuka +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Panduan visual untuk setiap bahagian papan pemuka OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Pembekal +## 🔌 Providers -Urus sambungan pembekal AI: Pembekal OAuth (Kod Claude, Codex, Gemini CLI), pembekal kunci API (Groq, DeepSeek, OpenRouter) dan pembekal percuma (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Kombo +## 🎨 Combos -Cipta gabungan penghalaan model dengan 6 strategi: isikan dahulu, bulat-bulat, kuasa-dua-pilihan, rawak, paling kurang digunakan dan dioptimumkan kos. Setiap kombo merantai berbilang model dengan sandaran automatik. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Analitis +## 📊 Analytics -Analitis penggunaan komprehensif dengan penggunaan token, anggaran kos, peta haba aktiviti, carta pengedaran mingguan dan pecahan setiap pembekal. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Kesihatan Sistem +## 🏥 System Health -Pemantauan masa nyata: masa aktif, memori, versi, persentil kependaman (p50/p95/p99), statistik cache dan keadaan pemutus litar pembekal. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Taman Permainan Penterjemah +## 🔧 Translator Playground -Empat mod untuk penyahpepijatan terjemahan API: **Taman Permainan** (penukar format), **Penguji Sembang** (permintaan langsung), ** Bangku Ujian** (ujian kelompok) dan **Monitor Langsung** (strim masa nyata). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Tetapan +## 🎮 Model Playground _(v2.0.9+)_ -Tetapan umum, storan sistem, pengurusan sandaran (pangkalan data eksport/import), penampilan (mod gelap/cahaya), keselamatan (termasuk perlindungan titik akhir API dan penyekatan pembekal tersuai), penghalaan, daya tahan dan konfigurasi lanjutan. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Alat CLI +## 🔧 CLI Tools -Konfigurasi satu klik untuk alat pengekodan AI: Kod Claude, Codex CLI, Gemini CLI, OpenClaw, Kod Kilo dan Antigraviti. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Log Permintaan +## 🤖 CLI Agents _(v2.0.11+)_ -Pengelogan permintaan masa nyata dengan penapisan mengikut pembekal, model, akaun dan kunci API. Menunjukkan kod status, penggunaan token, kependaman dan butiran respons. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Titik Akhir API +## 🌐 API Endpoint -Titik akhir API bersatu anda dengan pecahan keupayaan: Pelengkapan Sembang, Pembenaman, Penjanaan Imej, Kedudukan Semula, Transkripsi Audio dan kunci API berdaftar. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ms/TROUBLESHOOTING.md b/docs/i18n/ms/TROUBLESHOOTING.md index 6c55577f40..120092d63c 100644 --- a/docs/i18n/ms/TROUBLESHOOTING.md +++ b/docs/i18n/ms/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Penyelesaian masalah +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Masalah dan penyelesaian biasa untuk OmniRoute. +Common problems and solutions for OmniRoute. --- -## Pembetulan Pantas +## Quick Fixes -| Masalah | Penyelesaian | -| ---------------------------------------- | ------------------------------------------------------------------------ | -| Log masuk pertama tidak berfungsi | Tandai `INITIAL_PASSWORD` dalam `.env` (lalai: `123456`) | -| Papan pemuka dibuka pada port yang salah | Tetapkan `PORT=20128` dan `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Tiada log permintaan di bawah `logs/` | Tetapkan `ENABLE_REQUEST_LOGS=true` | -| EACCES: kebenaran ditolak | Tetapkan `DATA_DIR=/path/to/writable/dir` untuk mengatasi `~/.omniroute` | -| Strategi penghalaan tidak menyimpan | Kemas kini kepada v1.4.11+ (Pembetulan skema Zod untuk tetapan tetapan) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Isu Pembekal +## Provider Issues -### "Model bahasa tidak memberikan mesej" +### "Language model did not provide messages" -**Punca:** Kuota pembekal habis. +**Cause:** Provider quota exhausted. -**Betulkan:** +**Fix:** -1. Semak penjejak kuota papan pemuka -2. Gunakan kombo dengan peringkat sandaran -3. Tukar kepada peringkat yang lebih murah/percuma +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Mengehadkan Kadar +### Rate Limiting -**Punca:** Kuota langganan habis. +**Cause:** Subscription quota exhausted. -**Betulkan:** +**Fix:** -- Tambahkan sandaran: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Gunakan GLM/MiniMax sebagai sandaran murah +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Token OAuth Tamat Tempoh +### OAuth Token Expired -Token auto-refresh OmniRoute. Jika isu berterusan: +OmniRoute auto-refreshes tokens. If issues persist: -1. Papan pemuka → Pembekal → Sambung semula -2. Padam dan tambah semula sambungan pembekal +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Isu Awan +## Cloud Issues -### Ralat Penyegerakan Awan +### Cloud Sync Errors -1. Sahkan `BASE_URL` mata kepada contoh larian anda (cth., `http://localhost:20128`) -2. Sahkan `CLOUD_URL` mata ke titik akhir awan anda (cth., `https://omniroute.dev`) -3. Pastikan nilai `NEXT_PUBLIC_*` sejajar dengan nilai sebelah pelayan +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Mengembalikan 500 +### Cloud `stream=false` Returns 500 -**Simptom:** `Unexpected token 'd'...` pada titik akhir awan untuk panggilan bukan penstriman. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Punca:** Hulu mengembalikan muatan SSE sementara pelanggan menjangkakan JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Penyelesaian:** Gunakan `stream=true` untuk panggilan terus awan. Masa jalan tempatan termasuk SSE→JSON sandaran. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud Says Connected tetapi "Kunci API Tidak Sah" +### Cloud Says Connected but "Invalid API key" -1. Cipta kunci baharu daripada papan pemuka setempat (`/api/keys`) -2. Jalankan penyegerakan awan: Dayakan Awan → Segerakkan Sekarang -3. Kekunci lama/tidak disegerakkan masih boleh mengembalikan `401` pada awan +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Isu Docker +## Docker Issues -### Rancangan Alat CLI Tidak Dipasang +### CLI Tool Shows Not Installed -1. Semak medan masa jalan: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Untuk mod mudah alih: gunakan sasaran imej `runner-cli` (CLI dibundel) -3. Untuk mod lekap hos: tetapkan `CLI_EXTRA_PATHS` dan lekapkan direktori bin hos sebagai baca sahaja -4. Jika `installed=true` dan `runnable=false`: binari ditemui tetapi gagal pemeriksaan kesihatan +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Pengesahan Masa Jalan Pantas +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Isu Kos +## Cost Issues -### Kos Tinggi +### High Costs -1. Semak statistik penggunaan dalam Papan Pemuka → Penggunaan -2. Tukar model utama kepada GLM/MiniMax -3. Gunakan peringkat percuma (Gemini CLI, iFlow) untuk tugasan yang tidak kritikal -4. Tetapkan belanjawan kos setiap kunci API: Papan Pemuka → Kunci API → Belanjawan +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Penyahpepijatan +## Debugging -### Dayakan Log Permintaan +### Enable Request Logs -Tetapkan `ENABLE_REQUEST_LOGS=true` dalam fail `.env` anda. Log muncul di bawah direktori `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Semak Kesihatan Pembekal +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Storan Masa Jalan +### Runtime Storage -- Keadaan utama: `${DATA_DIR}/db.json` (penyedia, gabungan, alias, kunci, tetapan) -- Penggunaan: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Log permintaan: `/logs/...` (apabila `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Isu Pemutus Litar +## Circuit Breaker Issues -### Penyedia tersekat dalam keadaan OPEN +### Provider stuck in OPEN state -Apabila pemutus litar pembekal DIBUKA, permintaan disekat sehingga tempoh bertenang tamat. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Betulkan:** +**Fix:** -1. Pergi ke **Papan Pemuka → Tetapan → Ketahanan** -2. Periksa kad pemutus litar untuk pembekal yang terjejas -3. Klik **Tetapkan Semula Semua** untuk mengosongkan semua pemutus, atau tunggu sehingga tempoh bertenang tamat -4. Sahkan pembekal sebenarnya tersedia sebelum menetapkan semula +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Pembekal terus tersandung pemutus litar +### Provider keeps tripping the circuit breaker -Jika pembekal berulang kali memasuki keadaan OPEN: +If a provider repeatedly enters OPEN state: -1. Semak **Papan Pemuka → Kesihatan → Kesihatan Pembekal** untuk corak kegagalan -2. Pergi ke **Tetapan → Ketahanan → Profil Pembekal** dan tingkatkan ambang kegagalan -3. Semak sama ada pembekal telah menukar had API atau memerlukan pengesahan semula -4. Semak telemetri kependaman — kependaman tinggi boleh menyebabkan kegagalan berdasarkan tamat masa +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Isu Transkripsi Audio +## Audio Transcription Issues -### Ralat "Model tidak disokong". +### "Unsupported model" error -- Pastikan anda menggunakan awalan yang betul: `deepgram/nova-3` atau `assemblyai/best` -- Sahkan pembekal disambungkan dalam **Papan Pemuka → Pembekal** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Transkripsi mengembalikan kosong atau gagal +### Transcription returns empty or fails -- Semak format audio yang disokong: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Sahkan saiz fail berada dalam had pembekal (biasanya < 25MB) -- Semak kesahihan kunci API pembekal dalam kad pembekal +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Penyahpepijatan Penterjemah +## Translator Debugging -Gunakan **Papan Pemuka → Penterjemah** untuk menyahpepijat isu terjemahan format: +Use **Dashboard → Translator** to debug format translation issues: -| Mod | Bila Menggunakan | -| --------------------- | ------------------------------------------------------------------------------------------------------------------ | -| **Taman Permainan** | Bandingkan format input/output sebelah menyebelah — tampal permintaan yang gagal untuk melihat cara ia menterjemah | -| **Penguji Sembang** | Hantar mesej langsung dan periksa muatan penuh permintaan/tindak balas termasuk pengepala | -| **Bangku Ujian** | Jalankan ujian kelompok merentas gabungan format untuk mencari terjemahan yang rosak | -| **Pemantau Langsung** | Tonton aliran permintaan masa nyata untuk menangkap isu terjemahan terputus-putus | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Isu format biasa +### Common format issues -- **Teg pemikiran tidak muncul** — Semak sama ada pembekal sasaran menyokong pemikiran dan tetapan belanjawan pemikiran -- **Panggilan alat terputus** — Sesetengah terjemahan format mungkin menanggalkan medan yang tidak disokong; sahkan dalam mod Taman Permainan -- **Gesaan sistem tiada** — Gesaan sistem pengendalian Claude dan Gemini secara berbeza; semak output terjemahan -- **SDK mengembalikan rentetan mentah dan bukannya objek** — Ditetapkan dalam v1.1.0: sanitizer respons kini menanggalkan medan bukan standard (`x_groq`, `usage_breakdown`, dsb.) yang menyebabkan kegagalan pengesahan OpenAI SDK Pydantic -- **GLM/ERNIE menolak peranan `system`** — Ditetapkan dalam v1.1.0: penormal peranan secara automatik menggabungkan mesej sistem ke dalam mesej pengguna untuk model yang tidak serasi -- **`developer` peranan tidak dikenali** — Ditetapkan dalam v1.1.0: ditukar secara automatik kepada `system` untuk pembekal bukan OpenAI -- **`json_schema` tidak berfungsi dengan Gemini** — Ditetapkan dalam v1.1.0: `response_format` kini ditukar kepada Gemini `responseMimeType` + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Tetapan Ketahanan +## Resilience Settings -### Had kadar automatik tidak dicetuskan +### Auto rate-limit not triggering -- Had kadar automatik hanya digunakan untuk penyedia kunci API (bukan OAuth/langganan) -- Sahkan **Tetapan → Ketahanan → Profil Pembekal** telah didayakan had kadar automatik -- Semak sama ada pembekal mengembalikan kod status `429` atau pengepala `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Menala mundur eksponen +### Tuning exponential backoff -Profil pembekal menyokong tetapan ini: +Provider profiles support these settings: -- **Kelewatan asas** — Masa menunggu awal selepas kegagalan pertama (lalai: 1s) -- **Lengah maksimum** — Had masa menunggu maksimum (lalai: 30s) -- **Pendarab** — Berapa banyak untuk meningkatkan kelewatan setiap kegagalan berturut-turut (lalai: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Kumpulan anti-gemuruh +### Anti-thundering herd -Apabila banyak permintaan serentak melanda penyedia terhad kadar, OmniRoute menggunakan mutex + pengehadan kadar automatik untuk menyerikan permintaan dan mengelakkan kegagalan berlatarkan. Ini adalah automatik untuk pembekal kunci API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Masih Terperangkap? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Isu GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Seni Bina**: Lihat [link](ARCHITECTURE.md) untuk butiran dalaman -- **Rujukan API**: Lihat [link](API_REFERENCE.md) untuk semua titik akhir -- **Papan Pemuka Kesihatan**: Semak **Papan Pemuka → Kesihatan** untuk status sistem masa nyata -- **Penterjemah**: Gunakan **Papan Pemuka → Penterjemah** untuk menyahpepijat isu format +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/ms/USER_GUIDE.md b/docs/i18n/ms/USER_GUIDE.md index 549e46f0d7..5a043224df 100644 --- a/docs/i18n/ms/USER_GUIDE.md +++ b/docs/i18n/ms/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Panduan Pengguna +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Panduan lengkap untuk mengkonfigurasi penyedia, mencipta gabungan, menyepadukan alatan CLI dan menggunakan OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Jadual Kandungan +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Panduan lengkap untuk mengkonfigurasi penyedia, mencipta gabungan, menyepadukan --- -## 💰 Sekilas Pandang Harga +## 💰 Pricing at a Glance -| Peringkat | Pembekal | Kos | Set Semula Kuota | Terbaik Untuk | -| ---------------- | ---------------- | ----------------------- | ------------------ | ---------------------- | -| **💳 LANGGANAN** | Kod Claude (Pro) | $20/bln | 5j + mingguan | Sudah melanggan | -| | Codex (Plus/Pro) | $20-200/bln | 5j + mingguan | Pengguna OpenAI | -| | Gemini CLI | **PERCUMA** | 180K/bln + 1K/hari | Semua orang! | -| | GitHub Copilot | $10-19/bln | Bulanan | Pengguna GitHub | -| **🔑 KUNCI API** | DeepSeek | Bayar setiap penggunaan | Tiada | Penaakulan murah | -| | Groq | Bayar setiap penggunaan | Tiada | Inferens sangat pantas | -| | xAI (Grok) | Bayar setiap penggunaan | Tiada | Grok 4 penaakulan | -| | Mistral | Bayar setiap penggunaan | Tiada | Model yang dihoskan EU | -| | Kebingungan | Bayar setiap penggunaan | Tiada | Carian-ditambah | -| | Bersama AI | Bayar setiap penggunaan | Tiada | Model sumber terbuka | -| | Bunga Api AI | Bayar setiap penggunaan | Tiada | Imej FLUX Pantas | -| | Serebral | Bayar setiap penggunaan | Tiada | Kelajuan skala wafer | -| | Cohere | Bayar setiap penggunaan | Tiada | Perintah R+ RAG | -| | NVIDIA NIM | Bayar setiap penggunaan | Tiada | Model perusahaan | -| **💰 MURAH** | GLM-4.7 | $0.6/1J | Setiap hari 10AM | Sandaran belanjawan | -| | MiniMax M2.1 | $0.2/1J | 5 jam bergolek | Pilihan termurah | -| | Kimi K2 | $9/bln flat | 10 juta token/bln | Kos yang boleh diramal | -| **🆓 PERCUMA** | iFlow | $0 | tanpa had | 8 model percuma | -| | Qwen | $0 | tanpa had | 3 model percuma | -| | Kiro | $0 | tanpa had | Claude percuma | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Petua Pro:** Mulakan dengan Gemini CLI (180K percuma/bulan) + iFlow (percuma tanpa had) kombo = $0 kos! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Kes Penggunaan +## 🎯 Use Cases -### Kes 1: "Saya mempunyai langganan Claude Pro" +### Case 1: "I have Claude Pro subscription" -**Masalah:** Kuota tamat tempoh tidak digunakan, had kadar semasa pengekodan berat +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Kes 2: "Saya mahu kos sifar" +### Case 2: "I want zero cost" -**Masalah:** Tidak mampu membayar langganan, memerlukan pengekodan AI yang boleh dipercayai +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Kes 3: "Saya memerlukan pengekodan 24/7, tiada gangguan" +### Case 3: "I need 24/7 coding, no interruptions" -**Masalah:** Tarikh akhir, tidak mampu membayar masa henti +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Kes 4: "Saya mahukan AI PERCUMA dalam OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Masalah:** Memerlukan pembantu AI dalam apl pemesejan, percuma sepenuhnya +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Persediaan Pembekal +## 📖 Provider Setup -### 🔐 Pembekal Langganan +### 🔐 Subscription Providers -#### Kod Claude (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Petua Pro:** Gunakan Opus untuk tugas yang rumit, Sonnet untuk kelajuan. OmniRoute menjejaki kuota setiap model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (PERCUMA 180K/bulan!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Nilai Terbaik:** Peringkat percuma yang besar! Gunakan ini sebelum peringkat berbayar. +**Best Value:** Huge free tier! Use this before paid tiers. -#### Copilot GitHub +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Pembekal Murah +### 💰 Cheap Providers -#### GLM-4.7 (Tetapan semula harian, $0.6/1J) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Daftar: [Zhipu AI](https://open.bigmodel.cn/) -2. Dapatkan kunci API daripada Pelan Pengekodan -3. Papan Pemuka → Tambah Kunci API: Pembekal: `glm`, Kunci API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Gunakan:** `glm/glm-4.7` — **Petua Pro:** Pelan Pengekodan menawarkan kuota 3× pada 1/7 kos! Tetapkan semula setiap hari 10:00 AM. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (tetapan semula 5j, $0.20/1J) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Daftar: [MiniMax](https://www.minimax.io/) -2. Dapatkan kunci API → Papan Pemuka → Tambah Kunci API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Gunakan:** `minimax/MiniMax-M2.1` — **Petua Pro:** Pilihan termurah untuk konteks panjang (token 1M)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/bulan rata) +#### Kimi K2 ($9/month flat) -1. Langgan: [Moonshot AI](https://platform.moonshot.ai/) -2. Dapatkan kunci API → Papan Pemuka → Tambah Kunci API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Gunakan:** `kimi/kimi-latest` — **Petua Pro:** Tetap $9/bulan untuk 10 juta token = $0.90/1J kos efektif! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 Pembekal PERCUMA +### 🆓 FREE Providers -#### iFlow (8 model PERCUMA) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 model PERCUMA) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude PERCUMA) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Kombo +## 🎨 Combos -### Contoh 1: Maksimumkan Langganan → Sandaran Murah +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Contoh 2: Percuma-Sahaja (Kos Sifar) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 Integrasi CLI +## 🔧 CLI Integration -### IDE Kursor +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,7 +260,7 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Kod Claude +### Claude Code Edit `~/.claude/config.json`: @@ -303,9 +303,9 @@ Edit `~/.openclaw/openclaw.json`: } ``` -**Atau gunakan Papan Pemuka:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Teruskan / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Kerahan +## 🚀 Deployment -### Penggunaan VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### Doker +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Untuk mod bersepadu hos dengan binari CLI, lihat bahagian Docker dalam dokumen utama. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Pembolehubah Persekitaran +### Environment Variables -| Pembolehubah | Lalai | Penerangan | -| --------------------- | ------------------------------------ | ------------------------------------------------------------------ | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Rahsia menandatangani JWT (**perubahan dalam pengeluaran**) | -| `INITIAL_PASSWORD` | `123456` | Kata laluan log masuk pertama | -| `DATA_DIR` | `~/.omniroute` | Direktori data (db, penggunaan, log) | -| `PORT` | lalai rangka kerja | Port perkhidmatan (`20128` dalam contoh) | -| `HOSTNAME` | lalai rangka kerja | Ikat hos (Docker lalai kepada `0.0.0.0`) | -| `NODE_ENV` | lalai masa jalan | Tetapkan `production` untuk digunakan | -| `BASE_URL` | `http://localhost:20128` | URL asas dalaman sebelah pelayan | -| `CLOUD_URL` | `https://omniroute.dev` | URL asas titik akhir penyegerakan awan | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Rahsia HMAC untuk kunci API yang dijana | -| `REQUIRE_API_KEY` | `false` | Kuatkuasakan kunci API Pembawa pada `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Mendayakan log permintaan/tindak balas | -| `AUTH_COOKIE_SECURE` | `false` | Paksa `Secure` kuki pengesahan (di belakang proksi terbalik HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Untuk rujukan pembolehubah persekitaran penuh, lihat [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Model Tersedia +## 📊 Available Models
-Lihat semua model yang tersedia +View all available models -**Kod Claude (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Codex (`cx/`)** — Tambahan/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — PERCUMA: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — $0.6/1J: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $0.2/1J: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — PERCUMA: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — PERCUMA: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — PERCUMA: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,15 +460,15 @@ Untuk rujukan pembolehubah persekitaran penuh, lihat [README](../README.md). **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Kekeliruan (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Bersama AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Ai Bunga Api (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Serebral (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Kesatuan (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Untuk rujukan pembolehubah persekitaran penuh, lihat [README](../README.md). --- -## 🧩 Ciri Lanjutan +## 🧩 Advanced Features -### Model Tersuai +### Custom Models -Tambahkan sebarang ID model pada mana-mana pembekal tanpa menunggu kemas kini apl: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Atau gunakan Papan Pemuka: **Pembekal → [Penyedia] → Model Tersuai**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Laluan Penyedia Khusus +### Dedicated Provider Routes -Halakan permintaan terus kepada pembekal tertentu dengan pengesahan model: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Awalan pembekal ditambah secara automatik jika tiada. Model tidak sepadan mengembalikan `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Konfigurasi Proksi Rangkaian +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Keutamaan:** Khusus kunci → Khusus kombo → Khusus pembekal → Global → Persekitaran. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API Katalog Model +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Mengembalikan model yang dikumpulkan mengikut pembekal dengan jenis (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Penyegerakan Awan +### Cloud Sync -- Penyegerakan penyedia, gabungan dan tetapan merentas peranti -- Penyegerakan latar belakang automatik dengan tamat masa + cepat gagal -- Lebih suka bahagian pelayan `BASE_URL`/`CLOUD_URL` dalam pengeluaran +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### Perisikan Gerbang LLM (Fasa 9) +### LLM Gateway Intelligence (Phase 9) -- **Cache Semantik** — Auto-cache bukan penstriman, suhu=0 respons (pintasan dengan `X-OmniRoute-No-Cache: true`) -- **Minta Idempotency** — Menyahduplikasi permintaan dalam masa 5s melalui pengepala `Idempotency-Key` atau `X-Request-Id` -- **Penjejakan Kemajuan** — Ikut serta acara SSE `event: progress` melalui pengepala `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Taman Permainan Penterjemah +### Translator Playground -Akses melalui **Papan Pemuka → Penterjemah**. Nyahpepijat dan gambarkan cara OmniRoute menterjemah permintaan API antara pembekal. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Mod | Tujuan | -| --------------------- | -------------------------------------------------------------------------------------------------- | -| **Taman Permainan** | Pilih format sumber/sasaran, tampal permintaan dan lihat output yang diterjemahkan serta-merta | -| **Penguji Sembang** | Hantar mesej sembang langsung melalui proksi dan periksa kitaran permintaan/tindak balas penuh | -| **Bangku Ujian** | Jalankan ujian kelompok merentasi pelbagai kombinasi format untuk mengesahkan ketepatan terjemahan | -| **Pemantau Langsung** | Tonton terjemahan masa nyata apabila permintaan mengalir melalui proksi | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Kes penggunaan:** +**Use cases:** -- Nyahpepijat sebab gabungan klien/pembekal tertentu gagal -- Sahkan bahawa teg pemikiran, panggilan alat dan gesaan sistem diterjemahkan dengan betul -- Bandingkan perbezaan format antara format OpenAI, Claude, Gemini dan API Respons +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Strategi Penghalaan +### Routing Strategies -Konfigurasikan melalui **Papan Pemuka → Tetapan → Penghalaan**. +Configure via **Dashboard → Settings → Routing**. -| Strategi | Penerangan | -| --------------------------- | -------------------------------------------------------------------------------------------------------------- | -| **Isi Dulu** | Menggunakan akaun dalam susunan keutamaan — akaun utama mengendalikan semua permintaan sehingga tidak tersedia | -| **Robin Bulat** | Kitaran melalui semua akaun dengan had melekit boleh dikonfigurasikan (lalai: 3 panggilan setiap akaun) | -| **P2C (Kuasa Dua Pilihan)** | Pilih 2 akaun rawak dan laluan ke yang lebih sihat — mengimbangi beban dengan kesedaran kesihatan | -| **Rawak** | Memilih akaun secara rawak untuk setiap permintaan menggunakan Fisher-Yates shuffle | -| **Kurang Digunakan** | Laluan ke akaun dengan cap waktu `lastUsedAt` tertua, mengagihkan trafik secara sama rata | -| **Kos Dioptimumkan** | Laluan ke akaun dengan nilai keutamaan terendah, mengoptimumkan untuk pembekal kos terendah | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Alias Model Kad Liar +#### Wildcard Model Aliases -Cipta corak kad bebas untuk memetakan semula nama model: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Kad liar menyokong `*` (sebarang aksara) dan `?` (aksara tunggal). +Wildcards support `*` (any characters) and `?` (single character). -#### Rantai Fallback +#### Fallback Chains -Tentukan rantaian sandaran global yang digunakan merentas semua permintaan: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Ketahanan & Pemutus Litar +### Resilience & Circuit Breakers -Konfigurasikan melalui **Papan Pemuka → Tetapan → Ketahanan**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute melaksanakan daya tahan peringkat penyedia dengan empat komponen: +OmniRoute implements provider-level resilience with four components: -1. **Profil Pembekal** — Konfigurasi setiap pembekal untuk: - - Ambang kegagalan (berapa banyak kegagalan sebelum dibuka) - - Tempoh penyejukan - - Sensitiviti pengesanan had kadar - - Parameter mundur eksponen +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Had Kadar Boleh Diedit** — Lalai peringkat sistem boleh dikonfigurasikan dalam papan pemuka: - - **Permintaan Per Minit (RPM)** — Permintaan maksimum seminit setiap akaun - - **Masa Min Antara Permintaan** — Jurang minimum dalam milisaat antara permintaan - - **Permintaan Serentak Maks** — Permintaan serentak maksimum bagi setiap akaun - - Klik **Edit** untuk mengubah suai, kemudian **Simpan** atau **Batal**. Nilai kekal melalui API ketahanan. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Pemutus Litar** — Menjejaki kegagalan setiap pembekal dan membuka litar secara automatik apabila ambang dicapai: - - **TUTUP** (Sihat) — Permintaan mengalir seperti biasa - - **BUKA** — Pembekal disekat buat sementara waktu selepas kegagalan berulang - - **HALF_OPEN** — Menguji jika pembekal telah pulih +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Dasar & Pengecam Terkunci** — Menunjukkan status pemutus litar dan pengecam terkunci dengan keupayaan buka kunci paksa. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Pengesanan Auto Had Kadar** — Memantau pengepala `429` dan `Retry-After` untuk mengelak daripada mencapai had kadar penyedia secara proaktif. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Petua Pro:** Gunakan butang **Reset Semua** untuk mengosongkan semua pemutus litar dan cooldown apabila pembekal pulih daripada gangguan. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Eksport / Import Pangkalan Data +### Database Export / Import -Uruskan sandaran pangkalan data dalam **Papan Pemuka → Tetapan → Sistem & Storan**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Tindakan | Penerangan | -| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| **Eksport Pangkalan Data** | Memuat turun pangkalan data SQLite semasa sebagai fail `.sqlite` | -| **Eksport Semua (.tar.gz)** | Memuat turun arkib sandaran penuh termasuk: pangkalan data, tetapan, kombo, sambungan pembekal (tiada bukti kelayakan), metadata kunci API | -| **Import Pangkalan Data** | Muat naik fail `.sqlite` untuk menggantikan pangkalan data semasa. Sandaran pra-import dibuat secara automatik | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Pengesahan Import:** Fail yang diimport disahkan untuk integriti (semakan pragma SQLite), jadual yang diperlukan (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) dan saiz (maks 100MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Kes Penggunaan:** +**Use Cases:** -- Pindahkan OmniRoute antara mesin -- Buat sandaran luaran untuk pemulihan bencana -- Kongsi konfigurasi antara ahli pasukan (eksport semua → kongsi arkib) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Papan Pemuka Tetapan +### Settings Dashboard -Halaman tetapan disusun menjadi 5 tab untuk navigasi mudah: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Kandungan | -| --------------- | ------------------------------------------------------------------------------------------------------- | -| **Keselamatan** | Tetapan Log Masuk/Kata Laluan, Kawalan Akses IP, pengesahan API untuk `/models` dan Penyekatan Penyedia | -| **Penghalaan** | Strategi penghalaan global (6 pilihan), alias model kad bebas, rantai sandaran, lalai kombo | -| **Ketahanan** | Profil pembekal, had kadar boleh diedit, status pemutus litar, dasar & pengecam terkunci | -| **AI** | Pemikiran konfigurasi belanjawan, suntikan segera sistem global, statistik cache segera | -| **Lanjutan** | Konfigurasi proksi global (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Pengurusan Kos & Belanjawan +### Costs & Budget Management -Akses melalui **Papan Pemuka → Kos**. +Access via **Dashboard → Costs**. -| Tab | Tujuan | -| ------------ | ------------------------------------------------------------------------------------------------------------------- | -| **Anggaran** | Tetapkan had perbelanjaan bagi setiap kunci API dengan belanjawan harian/mingguan/bulanan dan penjejakan masa nyata | -| **Harga** | Lihat dan edit entri harga model — kos setiap token input/output 1K bagi setiap pembekal | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Penjejakan Kos:** Setiap permintaan merekodkan penggunaan token dan mengira kos menggunakan jadual harga. Lihat pecahan dalam **Papan Pemuka → Penggunaan** oleh pembekal, model dan kunci API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Transkripsi Audio +### Audio Transcription -OmniRoute menyokong transkripsi audio melalui titik akhir yang serasi dengan OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Pembekal yang tersedia: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Format audio yang disokong: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Strategi Pengimbangan Kombo +### Combo Balancing Strategies -Konfigurasikan pengimbangan setiap kombo dalam **Papan Pemuka → Kombo → Cipta/Edit → Strategi**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategi | Penerangan | -| -------------------- | ---------------------------------------------------------------------------------------- | -| **Round-Robin** | Berputar melalui model secara berurutan | -| **Keutamaan** | Sentiasa mencuba model pertama; jatuh semula hanya atas kesilapan | -| **Rawak** | Memilih model rawak daripada kombo untuk setiap permintaan | -| **Ditimbang** | Laluan secara berkadar berdasarkan berat yang ditetapkan bagi setiap model | -| **Kurang Digunakan** | Laluan ke model dengan permintaan terkini yang paling sedikit (menggunakan metrik kombo) | -| **Dioptimumkan Kos** | Laluan ke model yang tersedia paling murah (menggunakan jadual harga) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Lalai kombo global boleh ditetapkan dalam **Papan Pemuka → Tetapan → Penghalaan → Lalai Kombo**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Papan Pemuka Kesihatan +### Health Dashboard -Akses melalui **Papan Pemuka → Kesihatan**. Gambaran keseluruhan kesihatan sistem masa nyata dengan 6 kad: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Kad | Apa yang Ditunjukkan | -| ---------------------- | ------------------------------------------------------------------------ | -| **Status Sistem** | Masa aktif, versi, penggunaan memori, direktori data | -| **Kesihatan Pembekal** | Keadaan pemutus litar setiap pembekal (Tertutup/Terbuka/Separuh Terbuka) | -| **Had Kadar** | Cooldown had kadar aktif bagi setiap akaun dengan baki masa | -| **Sekat Aktif** | Pembekal disekat buat sementara waktu oleh dasar kunci keluar | -| **Tandatangan Cache** | Statistik cache penyahduplikasian (kunci aktif, kadar pukulan) | -| **Telemetri Latensi** | p50/p95/p99 pengagregatan kependaman bagi setiap pembekal | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Petua Pro:** Halaman Kesihatan dimuat semula secara automatik setiap 10 saat. Gunakan kad pemutus litar untuk mengenal pasti penyedia yang mengalami masalah. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/nl/API_REFERENCE.md b/docs/i18n/nl/API_REFERENCE.md index ea47a666cb..b795722c11 100644 --- a/docs/i18n/nl/API_REFERENCE.md +++ b/docs/i18n/nl/API_REFERENCE.md @@ -1,12 +1,12 @@ -# API-referentie +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Volledige referentie voor alle OmniRoute API-eindpunten. +Complete reference for all OmniRoute API endpoints. --- -## Inhoudsopgave +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Volledige referentie voor alle OmniRoute API-eindpunten. --- -## Chat-voltooiingen +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Aangepaste kopteksten +### Custom Headers -| Kop | Richting | Beschrijving | -| ------------------------ | -------- | ------------------------------------------------- | -| `X-OmniRoute-No-Cache` | Verzoek | Stel in op `true` om cache te omzeilen | -| `X-OmniRoute-Progress` | Verzoek | Ingesteld op `true` voor voortgangsgebeurtenissen | -| `Idempotency-Key` | Verzoek | Ontdubbelingssleutel (5s-venster) | -| `X-Request-Id` | Verzoek | Alternatieve ontdubbelsleutel | -| `X-OmniRoute-Cache` | Reactie | `HIT` of `MISS` (niet-streaming) | -| `X-OmniRoute-Idempotent` | Reactie | `true` indien ontdubbeld | -| `X-OmniRoute-Progress` | Reactie | `enabled` als voortgangsregistratie op | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Insluitingen +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Beschikbare providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Beeldgeneratie +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Beschikbare providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Lijstmodellen +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Compatibiliteitseindpunten +## Compatibility Endpoints -| Werkwijze | Pad | Formaat | -| --------- | --------------------------- | -------------------------- | -| POST | `/v1/chat/completions` | Open AI | -| POST | `/v1/messages` | Antropisch | -| POST | `/v1/responses` | OpenAI-reacties | -| POST | `/v1/embeddings` | Open AI | -| POST | `/v1/images/generations` | Open AI | -| KRIJG | `/v1/models` | Open AI | -| POST | `/v1/messages/count_tokens` | Antropisch | -| KRIJG | `/v1beta/models` | Tweeling | -| POST | `/v1beta/models/{...path}` | Tweelingen genererenInhoud | -| POST | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Speciale providerroutes +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Het providervoorvoegsel wordt automatisch toegevoegd als het ontbreekt. Niet-overeenkomende modellen retourneren `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Semantische cache +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Voorbeeld van een antwoord: +Response example: ```json { @@ -162,154 +162,164 @@ Voorbeeld van een antwoord: --- -## Dashboard en beheer +## Dashboard & Management -### Authenticatie +### Authentication -| Eindpunt | Werkwijze | Beschrijving | -| ----------------------------- | --------- | ------------------------ | -| `/api/auth/login` | POST | Inloggen | -| `/api/auth/logout` | POST | Uitloggen | -| `/api/settings/require-login` | KRIJG/ZET | Schakel inloggen vereist | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Providerbeheer +### Provider Management -| Eindpunt | Werkwijze | Beschrijving | -| ---------------------------- | ------------------------ | ------------------------------ | -| `/api/providers` | KRIJGEN/POST | Providers weergeven / aanmaken | -| `/api/providers/[id]` | KRIJGEN/ZET/VERWIJDEREN | Beheer een aanbieder | -| `/api/providers/[id]/test` | POST | Providerverbinding testen | -| `/api/providers/[id]/models` | KRIJG | Providermodellen weergeven | -| `/api/providers/validate` | POST | Providerconfiguratie valideren | -| `/api/provider-nodes*` | Diverse | Beheer van providerknooppunten | -| `/api/provider-models` | KRIJGEN/POST/VERWIJDEREN | Aangepaste modellen | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth-stromen +### OAuth Flows -| Eindpunt | Werkwijze | Beschrijving | -| -------------------------------- | --------- | ------------------------ | -| `/api/oauth/[provider]/[action]` | Diverse | Providerspecifieke OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Routering en configuratie +### Routing & Config -| Eindpunt | Werkwijze | Beschrijving | -| --------------------- | ------------ | ---------------------------------- | -| `/api/models/alias` | KRIJGEN/POST | Modelaliassen | -| `/api/models/catalog` | KRIJG | Alle modellen per aanbieder + type | -| `/api/combos*` | Diverse | Combinatiebeheer | -| `/api/keys*` | Diverse | API-sleutelbeheer | -| `/api/pricing` | KRIJG | Modelprijzen | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Gebruik en analyse +### Usage & Analytics -| Eindpunt | Werkwijze | Beschrijving | -| --------------------------- | --------- | --------------------------- | -| `/api/usage/history` | KRIJG | Gebruiksgeschiedenis | -| `/api/usage/logs` | KRIJG | Gebruikslogboeken | -| `/api/usage/request-logs` | KRIJG | Logboeken op aanvraagniveau | -| `/api/usage/[connectionId]` | KRIJG | Gebruik per verbinding | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Instellingen +### Settings -| Eindpunt | Werkwijze | Beschrijving | -| ------------------------------- | --------- | -------------------------------- | -| `/api/settings` | KRIJG/ZET | Algemene instellingen | -| `/api/settings/proxy` | KRIJG/ZET | Netwerkproxyconfiguratie | -| `/api/settings/proxy/test` | POST | Proxyverbinding testen | -| `/api/settings/ip-filter` | KRIJG/ZET | IP-toelatingslijst/blokkeerlijst | -| `/api/settings/thinking-budget` | KRIJG/ZET | Redeneren tokenbudget | -| `/api/settings/system-prompt` | KRIJG/ZET | Globale systeemprompt | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Toezicht +### Monitoring -| Eindpunt | Werkwijze | Beschrijving | -| ------------------------ | ------------------- | -------------------------- | -| `/api/sessions` | KRIJG | Actieve sessietracking | -| `/api/rate-limits` | KRIJG | Tarieflimieten per account | -| `/api/monitoring/health` | KRIJG | Gezondheidscontrole | -| `/api/cache` | OPHALEN/VERWIJDEREN | Cachestatistieken / wissen | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Back-up & exporteren/importeren +### Backup & Export/Import -| Eindpunt | Werkwijze | Beschrijving | -| --------------------------- | --------- | ------------------------------------------------ | -| `/api/db-backups` | KRIJG | Beschikbare back-ups weergeven | -| `/api/db-backups` | ZET | Maak een handmatige back-up | -| `/api/db-backups` | POST | Herstellen vanaf een specifieke back-up | -| `/api/db-backups/export` | KRIJG | Database downloaden als .sqlite-bestand | -| `/api/db-backups/import` | POST | Upload .sqlite-bestand om database te vervangen | -| `/api/db-backups/exportAll` | KRIJG | Volledige back-up downloaden als .tar.gz-archief | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Cloudsynchronisatie +### Cloud Sync -| Eindpunt | Werkwijze | Beschrijving | -| ---------------------- | --------- | ------------------------------ | -| `/api/sync/cloud` | Diverse | Cloudsynchronisatiebewerkingen | -| `/api/sync/initialize` | POST | Synchronisatie initialiseren | -| `/api/cloud/*` | Diverse | Cloudbeheer | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI-hulpmiddelen +### CLI Tools -| Eindpunt | Werkwijze | Beschrijving | -| ---------------------------------- | --------- | -------------------- | -| `/api/cli-tools/claude-settings` | KRIJG | Claude CLI-status | -| `/api/cli-tools/codex-settings` | KRIJG | Codex CLI-status | -| `/api/cli-tools/droid-settings` | KRIJG | Droid CLI-status | -| `/api/cli-tools/openclaw-settings` | KRIJG | OpenClaw CLI-status | -| `/api/cli-tools/runtime/[toolId]` | KRIJG | Algemene CLI-runtime | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -CLI-reacties omvatten: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Veerkracht en snelheidslimieten +### ACP Agents -| Eindpunt | Werkwijze | Beschrijving | -| ----------------------- | --------- | --------------------------------------- | -| `/api/resilience` | KRIJG/ZET | Veerkrachtprofielen ophalen/bijwerken | -| `/api/resilience/reset` | POST | Stroomonderbrekers resetten | -| `/api/rate-limits` | KRIJG | Status van tarieflimiet per account | -| `/api/rate-limit` | KRIJG | Configuratie van globale tarieflimieten | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Evaluaties +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Eindpunt | Werkwijze | Beschrijving | -| ------------ | ------------ | ----------------------------------------------- | -| `/api/evals` | KRIJGEN/POST | Evaluatiesuites weergeven / evaluatie uitvoeren | +### Resilience & Rate Limits -### Beleid +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Eindpunt | Werkwijze | Beschrijving | -| --------------- | ------------------------ | --------------------- | -| `/api/policies` | KRIJGEN/POST/VERWIJDEREN | Routingbeleid beheren | +### Evals -### Naleving +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Eindpunt | Werkwijze | Beschrijving | -| --------------------------- | --------- | --------------------------------- | -| `/api/compliance/audit-log` | KRIJG | Nalevingsauditlogboek (laatste N) | +### Policies -### v1beta (Gemini-compatibel) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Eindpunt | Werkwijze | Beschrijving | -| -------------------------- | --------- | --------------------------------- | -| `/v1beta/models` | KRIJG | Lijstmodellen in Gemini-formaat | -| `/v1beta/models/{...path}` | POST | Gemini `generateContent` eindpunt | +### Compliance -Deze eindpunten weerspiegelen het API-formaat van Gemini voor klanten die native Gemini SDK-compatibiliteit verwachten. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### Interne/systeem-API's +### v1beta (Gemini-Compatible) -| Eindpunt | Werkwijze | Beschrijving | -| --------------- | --------- | -------------------------------------------------------------- | -| `/api/init` | KRIJG | Initialisatiecontrole van applicatie (gebruikt bij eerste run) | -| `/api/tags` | KRIJG | Ollama-compatibele modeltags (voor Ollama-klanten) | -| `/api/restart` | POST | Trigger een sierlijke herstart van de server | -| `/api/shutdown` | POST | Trigger een elegante serveruitschakeling | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Opmerking:** Deze eindpunten worden intern gebruikt door het systeem of voor Ollama-clientcompatibiliteit. Ze worden doorgaans niet door eindgebruikers gebeld. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Audiotranscriptie +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transcribeer audiobestanden met Deepgram of AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Verzoek:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Reactie:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Ondersteunde providers:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Ondersteunde formaten:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Ollama-compatibiliteit +## Ollama Compatibility -Voor klanten die het API-formaat van Ollama gebruiken: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Verzoeken worden automatisch vertaald tussen Ollama en interne formaten. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetrie +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Reactie:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Begroting +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Beschikbaarheid van modellen +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Verzoekverwerking +## Request Processing -1. Klant stuurt verzoek naar `/v1/*` -2. Route-handleraanroepen `handleChat`, `handleEmbedding`, `handleAudioTranscription` of `handleImageGeneration` -3. Model is opgelost (directe provider/model of alias/combo) -4. Inloggegevens geselecteerd uit lokale DB met filtering van accountbeschikbaarheid -5. Voor chat: `handleChatCore` — formaatdetectie, vertaling, cachecontrole, idempotentiecontrole -6. Provider-uitvoerder verzendt een upstream-verzoek -7. Antwoord terugvertaald naar clientformaat (chat) of geretourneerd zoals het is (insluitingen/afbeeldingen/audio) -8. Verbruik/logboekregistratie -9. Fallback is van toepassing op fouten volgens comboregels +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Volledige architectuurreferentie: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Authenticatie +## Authentication -- Dashboardroutes (`/dashboard/*`) gebruiken `auth_token` cookie -- Inloggen maakt gebruik van opgeslagen wachtwoord-hash; terugval naar `INITIAL_PASSWORD` -- `requireLogin` schakelbaar via `/api/settings/require-login` -- Voor `/v1/*` routes is optioneel een Bearer API-sleutel vereist wanneer `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/nl/ARCHITECTURE.md b/docs/i18n/nl/ARCHITECTURE.md index 2027e553e0..258d62df53 100644 --- a/docs/i18n/nl/ARCHITECTURE.md +++ b/docs/i18n/nl/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# OmniRoute-architectuur +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Laatst bijgewerkt: 2026-02-18_ +_Last updated: 2026-03-04_ -## Samenvatting +## Executive Summary -OmniRoute is een lokale AI-routeringsgateway en dashboard gebouwd op Next.js. -Het biedt één OpenAI-compatibel eindpunt (`/v1/*`) en routeert verkeer over meerdere upstream-providers met vertaling, fallback, tokenvernieuwing en gebruiksregistratie. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Kernmogelijkheden: +Core capabilities: -- OpenAI-compatibel API-oppervlak voor CLI/tools (28 providers) -- Verzoek/antwoord-vertaling in verschillende providerformaten -- Modelcombo fallback (reeks met meerdere modellen) -- Terugval op accountniveau (meerdere accounts per provider) -- OAuth + API-sleutelproviderverbindingsbeheer -- Generatie inbedden via `/v1/embeddings` (6 providers, 9 modellen) -- Beeldgeneratie via `/v1/images/generations` (4 providers, 9 modellen) -- Denk aan het parseren van tags (`...`) voor redeneermodellen -- Reactieopschoning voor strikte OpenAI SDK-compatibiliteit -- Rolnormalisatie (ontwikkelaar → systeem, systeem → gebruiker) voor compatibiliteit tussen providers -- Gestructureerde uitvoerconversie (json_schema → Gemini responseSchema) -- Lokale persistentie voor providers, sleutels, aliassen, combo's, instellingen, prijzen -- Gebruik/kosten bijhouden en verzoekregistratie -- Optionele cloudsynchronisatie voor synchronisatie van meerdere apparaten/statussen -- IP-toelatingslijst/blokkeerlijst voor API-toegangscontrole -- Meedenken over budgetbeheer (passthrough/auto/custom/adaptive) -- Globale systeemprompt-injectie -- Sessie volgen en vingerafdrukken maken -- Verbeterde tarieflimieten per account met providerspecifieke profielen -- Stroomonderbrekerpatroon voor veerkracht van de provider -- Bescherming tegen donderende kuddes met mutex-vergrendeling -- Op handtekeningen gebaseerde cache voor deduplicatie van verzoeken -- Domeinlaag: modelbeschikbaarheid, kostenregels, fallback-beleid, lock-outbeleid -- Persistentie van domeinstatus (SQLite-schrijfcache voor fallbacks, budgetten, uitsluitingen, stroomonderbrekers) -- Beleidsengine voor gecentraliseerde verzoekevaluatie (lockout → budget → fallback) -- Telemetrie aanvragen met p50/p95/p99-latency-aggregatie -- Correlatie-ID (X-Request-Id) voor end-to-end tracering -- Compliance-auditregistratie met opt-out per API-sleutel -- Evaluatiekader voor LLM-kwaliteitsborging -- Veerkracht UI-dashboard met realtime stroomonderbrekerstatus -- Modulaire OAuth-providers (12 afzonderlijke modules onder `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Primair runtimemodel: +Primary runtime model: -- Next.js-approutes onder `src/app/api/*` implementeren zowel dashboard-API's als compatibiliteits-API's -- Een gedeelde SSE/routing-kern in `src/sse/*` + `open-sse/*` zorgt voor de uitvoering, vertaling, streaming, fallback en gebruik van de provider +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Reikwijdte en grenzen +## Scope and Boundaries -### Binnen bereik +### In Scope -- Lokale gateway-runtime -- Dashboardbeheer-API's -- Providerverificatie en tokenvernieuwing -- Vraag vertaling en SSE-streaming aan -- Lokale status + gebruikspersistentie -- Optionele cloudsynchronisatie-orkestratie +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Buiten bereik +### Out of Scope -- Implementatie van cloudservices achter `NEXT_PUBLIC_CLOUD_URL` -- Provider SLA/controlevlak buiten het lokale proces -- Externe CLI-binaire bestanden zelf (Claude CLI, Codex CLI, enz.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Systeemcontext op hoog niveau +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Kernruntime-componenten +## Core Runtime Components -## 1) API- en routeringslaag (Next.js app-routes) +## 1) API and Routing Layer (Next.js App Routes) -Hoofdmappen: +Main directories: -- `src/app/api/v1/*` en `src/app/api/v1beta/*` voor compatibiliteits-API's -- `src/app/api/*` voor beheer-/configuratie-API's -- Volgende herschrijvingen in `next.config.mjs` brengen `/v1/*` in kaart naar `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Belangrijke compatibiliteitsroutes: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — bevat aangepaste modellen met `custom: true` -- `src/app/api/v1/embeddings/route.ts` — generatie van inbedding (6 providers) -- `src/app/api/v1/images/generations/route.ts` — genereren van afbeeldingen (4+ providers incl. Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — speciale chat per provider -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — speciale insluitingen per provider -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — speciale afbeeldingen per provider +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Beheerdomeinen: +Management domains: -- Authenticatie/instellingen: `src/app/api/auth/*`, `src/app/api/settings/*` -- Providers/verbindingen: `src/app/api/providers*` -- Providerknooppunten: `src/app/api/provider-nodes*` -- Aangepaste modellen: `src/app/api/provider-models` (GET/POST/DELETE) -- Modelcatalogus: `src/app/api/models/catalog` (GET) -- Proxyconfiguratie: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Sleutels/aliassen/combo's/prijzen: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Gebruik: `src/app/api/usage/*` -- Synchroniseren/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI-hulpmiddelen: `src/app/api/cli-tools/*` -- IP-filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Denkbudget: `src/app/api/settings/thinking-budget` (GET/PUT) -- Systeemprompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessies: `src/app/api/sessions` (KRIJGEN) -- Tarieflimieten: `src/app/api/rate-limits` (GET) -- Veerkracht: `src/app/api/resilience` (GET/PATCH) — providerprofielen, stroomonderbreker, snelheidslimietstatus -- Veerkracht reset: `src/app/api/resilience/reset` (POST) — reset onderbrekers + cooldowns -- Cachestatistieken: `src/app/api/cache/stats` (GET/DELETE) -- Beschikbaarheid van modellen: `src/app/api/models/availability` (GET/POST) -- Telemetrie: `src/app/api/telemetry/summary` (GET) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) - Budget: `src/app/api/usage/budget` (GET/POST) -- Terugvalketens: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Nalevingsaudit: `src/app/api/compliance/audit-log` (GET) -- Evaluaties: `src/app/api/evals` (KRIJGEN/POST), `src/app/api/evals/[suiteId]` (KRIJGEN) -- Beleid: `src/app/api/policies` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + vertaalkern +## 2) SSE + Translation Core -Hoofdstroommodules: +Main flow modules: -- Toegang: `src/sse/handlers/chat.ts` -- Kernorkestratie: `open-sse/handlers/chatCore.ts` -- Uitvoeringsadapters van provider: `open-sse/executors/*` -- Formaatdetectie/providerconfiguratie: `open-sse/services/provider.ts` -- Model parseren/oplossen: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Reservelogica voor accounts: `open-sse/services/accountFallback.ts` -- Vertaalregister: `open-sse/translator/index.ts` -- Streamtransformaties: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Gebruiksextractie/normalisatie: `open-sse/utils/usageTracking.ts` -- Denk aan tag-parser: `open-sse/utils/thinkTagParser.ts` -- Inbeddingshandler: `open-sse/handlers/embeddings.ts` -- Providerregister insluiten: `open-sse/config/embeddingRegistry.ts` -- Handler voor het genereren van afbeeldingen: `open-sse/handlers/imageGeneration.ts` -- Register van beeldaanbieder: `open-sse/config/imageRegistry.ts` -- Reactie-opschoning: `open-sse/handlers/responseSanitizer.ts` -- Rolnormalisatie: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Diensten (bedrijfslogica): +Services (business logic): -- Accountselectie/score: `open-sse/services/accountSelector.ts` -- Contextlevenscyclusbeheer: `open-sse/services/contextManager.ts` -- Handhaving van IP-filter: `open-sse/services/ipFilter.ts` -- Sessie volgen: `open-sse/services/sessionManager.ts` -- Ontdubbeling aanvragen: `open-sse/services/signatureCache.ts` -- Systeemprompt injectie: `open-sse/services/systemPrompt.ts` -- Denken aan budgetbeheer: `open-sse/services/thinkingBudget.ts` -- Routering van wildcardmodellen: `open-sse/services/wildcardRouter.ts` -- Tarieflimietbeheer: `open-sse/services/rateLimitManager.ts` -- Stroomonderbreker: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Domeinlaagmodules: +Domain layer modules: -- Beschikbaarheid van modellen: `src/lib/domain/modelAvailability.ts` -- Kostenregels/budgetten: `src/lib/domain/costRules.ts` -- Terugvalbeleid: `src/lib/domain/fallbackPolicy.ts` -- Combo-oplosser: `src/lib/domain/comboResolver.ts` -- Uitsluitingsbeleid: `src/lib/domain/lockoutPolicy.ts` -- Beleidsengine: `src/domain/policyEngine.ts` — gecentraliseerde uitsluiting → budget → fallback-evaluatie -- Foutcodecatalogus: `src/lib/domain/errorCodes.ts` -- Verzoek-ID: `src/lib/domain/requestId.ts` -- Time-out ophalen: `src/lib/domain/fetchTimeout.ts` -- Telemetrie aanvragen: `src/lib/domain/requestTelemetry.ts` -- Naleving/audit: `src/lib/domain/compliance/index.ts` -- Evaluatie loper: `src/lib/domain/evalRunner.ts` -- Persistentie van domeinstatus: `src/lib/db/domainState.ts` — SQLite CRUD voor fallback-ketens, budgetten, kostengeschiedenis, uitsluitingsstatus, stroomonderbrekers +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth-providermodules (12 afzonderlijke bestanden onder `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Registerindex: `src/lib/oauth/providers/index.ts` -- Individuele providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Dunne verpakking: `src/lib/oauth/providers.ts` — exporteert opnieuw vanuit afzonderlijke modules +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Persistentielaag +## 3) Persistence Layer -Primaire staat DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- bestand: `${DATA_DIR}/db.json` (of `$XDG_CONFIG_HOME/omniroute/db.json` indien ingesteld, anders `~/.omniroute/db.json`) -- entiteiten: providerConnections, providerNodes, modelAliases, combo's, apiKeys, instellingen, prijzen, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Gebruiksdatabase: +Usage persistence: -- `src/lib/usageDb.ts` -- bestanden: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- volgt hetzelfde basismapbeleid als `localDb` (`DATA_DIR`, daarna `XDG_CONFIG_HOME/omniroute` indien ingesteld) -- opgesplitst in gerichte submodules: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -Domeinstatus DB (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — CRUD-bewerkingen voor domeinstatus -- Tabellen (aangemaakt in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Doorschrijfcachepatroon: kaarten in het geheugen zijn gezaghebbend tijdens runtime; mutaties worden synchroon naar SQLite geschreven; status wordt hersteld vanuit DB bij koude start +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Auth + beveiligingsoppervlakken +## 4) Auth + Security Surfaces -- Dashboardcookieverificatie: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- API-sleutel genereren/verificatie: `src/shared/utils/apiKey.ts` -- Providergeheimen bleven bestaan in `providerConnections` vermeldingen -- Ondersteuning voor uitgaande proxy's via `open-sse/utils/proxyFetch.ts` (env vars) en `open-sse/utils/networkProxy.ts` (configureerbaar per provider of wereldwijd) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Cloudsynchronisatie +## 5) Cloud Sync -- Initiële planner: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Periodieke taak: `src/shared/services/cloudSyncScheduler.ts` -- Controleroute: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Aanvraaglevenscyclus (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + terugvalstroom voor accounts +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Terugvalbeslissingen worden aangestuurd door `open-sse/services/accountFallback.ts` met behulp van statuscodes en heuristieken voor foutmeldingen. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth-onboarding en levenscyclus van tokenvernieuwing +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Vernieuwen tijdens live verkeer wordt uitgevoerd binnen `open-sse/handlers/chatCore.ts` via uitvoerder `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Cloud Sync-levenscyclus (inschakelen / synchroniseren / uitschakelen) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Periodieke synchronisatie wordt geactiveerd door `CloudSyncScheduler` wanneer de cloud is ingeschakeld. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Gegevensmodel en opslagkaart +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Fysieke opslagbestanden: +Physical storage files: -- hoofdstatus: `${DATA_DIR}/db.json` (of `$XDG_CONFIG_HOME/omniroute/db.json` indien ingesteld, anders `~/.omniroute/db.json`) -- gebruiksstatistieken: `${DATA_DIR}/usage.json` -- logregels opvragen: `${DATA_DIR}/log.txt` -- optionele foutopsporingssessies voor vertalers/verzoeken: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Implementatietopologie +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Moduletoewijzing (beslissingskritisch) +## Module Mapping (Decision-Critical) -### Route- en API-modules +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibiliteits-API's -- `src/app/api/v1/providers/[provider]/*`: speciale routes per provider (chat, insluitingen, afbeeldingen) -- `src/app/api/providers*`: provider CRUD, validatie, testen -- `src/app/api/provider-nodes*`: aangepast compatibel knooppuntbeheer -- `src/app/api/provider-models`: aangepast modelbeheer (CRUD) -- `src/app/api/models/catalog`: volledige modelcatalogus-API (alle typen gegroepeerd op provider) -- `src/app/api/oauth/*`: OAuth/apparaatcodestromen -- `src/app/api/keys*`: levenscyclus van lokale API-sleutel -- `src/app/api/models/alias`: aliasbeheer -- `src/app/api/combos*`: fallback-combobeheer -- `src/app/api/pricing`: prijsoverschrijvingen voor kostenberekening -- `src/app/api/settings/proxy`: proxyconfiguratie (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: uitgaande proxy-connectiviteitstest (POST) -- `src/app/api/usage/*`: API's voor gebruik en logboeken -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloudsynchronisatie en cloudgerichte helpers -- `src/app/api/cli-tools/*`: lokale CLI-configuratieschrijvers/-controleurs -- `src/app/api/settings/ip-filter`: IP-toelatingslijst/blokkeerlijst (GET/PUT) -- `src/app/api/settings/thinking-budget`: configuratie voor denkend tokenbudget (GET/PUT) -- `src/app/api/settings/system-prompt`: algemene systeemprompt (GET/PUT) -- `src/app/api/sessions`: actieve sessielijst (GET) -- `src/app/api/rate-limits`: tarieflimietstatus per account (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Routing- en uitvoeringskern +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: verzoekparse, combo-afhandeling, accountselectielus -- `open-sse/handlers/chatCore.ts`: vertaling, verzending van de uitvoerder, afhandeling van opnieuw proberen/vernieuwen, stream-instellingen -- `open-sse/executors/*`: providerspecifiek netwerk- en formaatgedrag +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Vertaalregister en formaatconverters +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: register en orkestratie van vertalers -- Vertalers aanvragen: `open-sse/translator/request/*` -- Antwoordvertalers: `open-sse/translator/response/*` -- Formaatconstanten: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Volharding +### Persistence -- `src/lib/localDb.ts`: persistente configuratie/status -- `src/lib/usageDb.ts`: gebruiksgeschiedenis en logbestanden met doorlopende aanvragen +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Dekking van de provider-uitvoerder (strategiepatroon) +## Provider Executor Coverage (Strategy Pattern) -Elke provider heeft een gespecialiseerde uitvoerder die `BaseExecutor` uitbreidt (in `open-sse/executors/base.ts`), die zorgt voor het bouwen van URL's, het bouwen van headers, nieuwe pogingen met exponentiële uitstel, hooks voor het vernieuwen van referenties en de orkestratiemethode `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| executeur | Aanbieder(s) | Speciale behandeling | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Verbijstering, Samen, Vuurwerk, Cerebras, Cohere, NVIDIA | Dynamische URL/header-configuratie per provider | -| `AntigravityExecutor` | Google Antizwaartekracht | Aangepaste project-/sessie-ID's, opnieuw proberen na parseren | -| `CodexExecutor` | OpenAI-codex | Injecteert systeeminstructies, dwingt redeneerinspanning af | -| `CursorExecutor` | Cursor-IDE | ConnectRPC-protocol, Protobuf-codering, ondertekening aanvragen via checksum | -| `GithubExecutor` | GitHub-copiloot | Copilot-token vernieuwen, VSCode-nabootsende headers | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binair formaat → SSE-conversie | -| `GeminiCLIExecutor` | Tweeling CLI | Vernieuwingscyclus van Google OAuth-token | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Alle andere providers (inclusief aangepaste compatibele knooppunten) gebruiken de `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Compatibiliteitsmatrix voor providers +## Provider Compatibility Matrix -| Aanbieder | Formaat | Autorisatie | Stroom | Niet-stream | Token vernieuwen | Gebruiks-API | -| ----------------- | ------------------ | ---------------------- | ---------------- | ----------- | ---------------- | -------------------------- | -| Claude | claude | API-sleutel / OAuth | ✅ | ✅ | ✅ | ⚠️Alleen beheerder | -| Tweeling | Tweeling | API-sleutel / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloudconsole | -| Tweeling CLI | tweeling-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloudconsole | -| Antizwaartekracht | anti-zwaartekracht | OAuth | ✅ | ✅ | ✅ | ✅ Volledige quota-API | -| Open AI | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-reacties | OAuth | ✅ gedwongen | ❌ | ✅ | ✅ Tarieflimieten | -| GitHub-copiloot | openai | OAuth + Copilot-token | ✅ | ✅ | ✅ | ✅ Momentopnamen van quota | -| Cursor | cursor | Aangepaste controlesom | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Gebruikslimieten | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️Per aanvraag | -| iFlow | openai | OAuth (basis) | ✅ | ✅ | ✅ | ⚠️Per aanvraag | -| OpenRouter | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| Verbijstering | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| Samen AI | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| Vuurwerk AI | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| Hersenen | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| Cohier | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API-sleutel | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Dekking van formaatvertalingen +## Format Translation Coverage -Gedetecteerde bronformaten zijn onder meer: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Doelformaten zijn onder meer: +Target formats include: -- OpenAI-chat/reacties - -Claude -- Gemini/Gemini-CLI/Antigravity-envelop +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope - Kiro - Cursor -Vertalingen gebruiken **OpenAI als hubformaat** — alle conversies gaan via OpenAI als tussenproduct: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Vertalingen worden dynamisch geselecteerd op basis van de vorm van de bronpayload en het doelformaat van de provider. +Translations are selected dynamically based on source payload shape and provider target format. -Extra verwerkingslagen in de vertaalpijplijn: +Additional processing layers in the translation pipeline: -- **Opschoning van reacties** — Verwijdert niet-standaardvelden uit reacties in OpenAI-formaat (zowel streaming als niet-streaming) om strikte SDK-naleving te garanderen -- **Rolnormalisatie** — Converteert `developer` → `system` voor niet-OpenAI-doelen; voegt `system` → `user` samen voor modellen die de systeemrol afwijzen (GLM, ERNIE) -- **Think tag-extractie** — Parseert `...` blokken uit de inhoud in het veld `reasoning_content` -- **Gestructureerde uitvoer** — Converteert OpenAI `response_format.json_schema` naar Gemini's `responseMimeType` + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Ondersteunde API-eindpunten +## Supported API Endpoints -| Eindpunt | Formaat | Behandelaar | -| -------------------------------------------------- | -------------------- | --------------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI-chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude-berichten | Dezelfde handler (automatisch gedetecteerd) | -| `POST /v1/responses` | OpenAI-reacties | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI-insluitingen | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Modellijst | API-route | -| `POST /v1/images/generations` | OpenAI-afbeeldingen | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Modellijst | API-route | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI-chat | Toegewijd per provider met modelvalidatie | -| `POST /v1/providers/{provider}/embeddings` | OpenAI-insluitingen | Toegewijd per provider met modelvalidatie | -| `POST /v1/providers/{provider}/images/generations` | OpenAI-afbeeldingen | Toegewijd per provider met modelvalidatie | -| `POST /v1/messages/count_tokens` | Claude-tokentelling | API-route | -| `GET /v1/models` | OpenAI-modellenlijst | API-route (chat + insluiten + afbeelding + aangepaste modellen) | -| `GET /api/models/catalog` | Catalogus | Alle modellen gegroepeerd op aanbieder + type | -| `POST /v1beta/models/*:streamGenerateContent` | Gemini geboren | API-route | -| `GET/PUT/DELETE /api/settings/proxy` | Proxyconfiguratie | Netwerkproxyconfiguratie | -| `POST /api/settings/proxy/test` | Proxy-connectiviteit | Eindpunt proxystatus/connectiviteitstest | -| `GET/POST/DELETE /api/provider-models` | Aangepaste modellen | Maatwerkmodelbeheer per provider | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Bypass-handler +## Bypass Handler -De bypass-handler (`open-sse/utils/bypassHandler.ts`) onderschept bekende "wegwerp"-verzoeken van Claude CLI (opwarmingspings, titelextracties en tokentellingen) en retourneert een **vals antwoord** zonder upstream-providertokens te verbruiken. Dit wordt alleen geactiveerd als `User-Agent` `claude-cli` bevat. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Loggerpijplijn aanvragen +## Request Logger Pipeline -De verzoeklogger (`open-sse/utils/requestLogger.ts`) biedt een pijplijn voor het opsporen van fouten in 7 fasen, standaard uitgeschakeld en ingeschakeld via `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Voor elke verzoeksessie worden bestanden naar `/logs//` geschreven. +Files are written to `/logs//` for each request session. -## Faalmodi en veerkracht +## Failure Modes and Resilience -## 1) Beschikbaarheid van account/provider +## 1) Account/Provider Availability -- Afkoelperiode van provideraccount bij tijdelijke/snelheids-/authenticatiefouten -- accountterugval voordat het verzoek mislukt -- Terugval op combo-modellen wanneer het huidige model-/providerpad is uitgeput +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Vervaldatum van token +## 2) Token Expiry -- vooraf controleren en vernieuwen met nieuwe poging voor vernieuwbare providers -- 401/403 opnieuw proberen na vernieuwingspoging in kernpad +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Streamveiligheid +## 3) Stream Safety -- verbindingsbewuste streamcontroller -- vertaalstroom met end-of-stream flush en `[DONE]` afhandeling -- Terugval in gebruiksschattingen wanneer metagegevens over het gebruik van de provider ontbreken +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Verslechtering van cloudsynchronisatie +## 4) Cloud Sync Degradation -- Er zijn synchronisatiefouten opgetreden, maar de lokale runtime gaat door -- Scheduler heeft logica die geschikt is voor opnieuw proberen, maar periodieke uitvoering roept momenteel standaard synchronisatie met één poging aan +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Gegevensintegriteit +## 5) Data Integrity -- DB-vormmigratie/reparatie voor ontbrekende sleutels -- corrupte JSON-resetbeveiligingen voor localDb en UseDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Waarneembaarheid en operationele signalen +## Observability and Operational Signals -Bronnen voor runtime-zichtbaarheid: +Runtime visibility sources: -- consolelogboeken van `src/sse/utils/logger.ts` -- gebruiksaggregaten per verzoek in `usage.json` -- tekstueel verzoek status inloggen `log.txt` -- optionele diepe verzoek-/vertaallogboeken onder `logs/` wanneer `ENABLE_REQUEST_LOGS=true` -- eindpunten voor dashboardgebruik (`/api/usage/*`) voor UI-verbruik +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Beveiligingsgevoelige grenzen +## Security-Sensitive Boundaries -- JWT-geheim (`JWT_SECRET`) beveiligt de verificatie/ondertekening van dashboardsessiecookies -- Initiële wachtwoord-fallback (`INITIAL_PASSWORD`, standaard `123456`) moet worden overschreven in echte implementaties -- API-sleutel HMAC-geheim (`API_KEY_SECRET`) beveiligt het gegenereerde lokale API-sleutelformaat -- Providergeheimen (API-sleutels/tokens) worden bewaard in de lokale database en moeten worden beschermd op bestandssysteemniveau -- Cloudsynchronisatie-eindpunten zijn afhankelijk van API-sleutelauthenticatie en machine-ID-semantiek +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Omgevings- en runtimematrix +## Environment and Runtime Matrix -Omgevingsvariabelen die actief worden gebruikt door code: +Environment variables actively used by code: -- App/authenticatie: `JWT_SECRET`, `INITIAL_PASSWORD` -- Opslag: `DATA_DIR` -- Compatibel knooppuntgedrag: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Optionele opslagbasisoverschrijving (Linux/macOS wanneer `DATA_DIR` niet is ingesteld): `XDG_CONFIG_HOME` -- Beveiligingshashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Logboekregistratie: `ENABLE_REQUEST_LOGS` -- Synchroniseren/cloud-URL's: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Uitgaande proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` en varianten in kleine letters -- SOCKS5-functievlaggen: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Platform-/runtime-helpers (niet app-specifieke configuratie): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Bekende architecturale aantekeningen +## Known Architectural Notes -1. `usageDb` en `localDb` delen nu hetzelfde basismapbeleid (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) met oudere bestandsmigratie. -2. `/api/v1/route.ts` retourneert een statische modellenlijst en is niet de belangrijkste modellenbron die wordt gebruikt door `/v1/models`. -3. Verzoeklogger schrijft volledige headers/body indien ingeschakeld; behandel de logmap als gevoelig. -4. Het cloudgedrag is afhankelijk van de juiste `NEXT_PUBLIC_BASE_URL` en bereikbaarheid van het cloudeindpunt. -5. De map `open-sse/` wordt gepubliceerd als het `@omniroute/open-sse` **npm-werkruimtepakket**. De broncode importeert deze via `@omniroute/open-sse/...` (opgelost door Next.js `transpilePackages`). Bestandspaden in dit document gebruiken nog steeds de mapnaam `open-sse/` voor consistentie. -6. Grafieken in het dashboard maken gebruik van **Recharts** (op SVG-basis) voor toegankelijke, interactieve analytische visualisaties (staafdiagrammen voor modelgebruik, uitsplitsingstabellen van providers met succespercentages). -7. E2E-tests gebruiken **Toneelschrijver** (`tests/e2e/`), uitgevoerd via `npm run test:e2e`. Eenheidstests gebruiken **Node.js testrunner** (`tests/unit/`), uitgevoerd via `npm run test:plan3`. Broncode onder `src/` is **TypeScript** (`.ts`/`.tsx`); de `open-sse/` werkruimte blijft JavaScript (`.js`). -8. De instellingenpagina is onderverdeeld in 5 tabbladen: Beveiliging, Routing (6 globale strategieën: eerst vullen, round-robin, p2c, willekeurig, minst gebruikt, kostengeoptimaliseerd), veerkracht (bewerkbare snelheidslimieten, stroomonderbreker, beleid), AI (denkbudget, systeemprompt, promptcache), Geavanceerd (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Operationele verificatiechecklist +## Operational Verification Checklist -- Bouw vanaf de bron: `npm run build` -- Bouw Docker-afbeelding: `docker build -t omniroute .` -- Start de service en controleer: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- CLI-doelbasis-URL moet `http://:20128/v1` zijn wanneer `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/nl/CODEBASE_DOCUMENTATION.md b/docs/i18n/nl/CODEBASE_DOCUMENTATION.md index 4a99fa3188..303880c198 100644 --- a/docs/i18n/nl/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/nl/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Codebase-documentatie +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Een uitgebreide, beginnersvriendelijke gids voor de **omniroute** AI-proxyrouter met meerdere providers. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Wat is omniroute? +## 1. What Is omniroute? -omniroute is een **proxyrouter** die zich tussen AI-clients (Claude CLI, Codex, Cursor IDE, enz.) en AI-providers (Anthropic, Google, OpenAI, AWS, GitHub, enz.) bevindt. Het lost één groot probleem op: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Verschillende AI-clients spreken verschillende "talen" (API-formaten), en verschillende AI-providers verwachten ook verschillende "talen".** omniroute vertaalt automatisch tussen hen. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Zie het als een universele vertaler bij de Verenigde Naties: elke afgevaardigde kan elke taal spreken, en de vertaler zet deze om voor elke andere afgevaardigde. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Architectuuroverzicht +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Kernprincipe: Hub-and-spoke-vertaling +### Core Principle: Hub-and-Spoke Translation -Alle formaatvertalingen passeren het **OpenAI-formaat als hub**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Dit betekent dat u slechts **N vertalers** nodig heeft (één per formaat) in plaats van **N²** (elk paar). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Projectstructuur +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Uitsplitsing per module +## 4. Module-by-Module Breakdown -### 4.1 configuratie (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -De **enige bron van waarheid** voor alle providerconfiguraties. +The **single source of truth** for all provider configuration. -| Bestand | Doel | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` object met basis-URL's, OAuth-inloggegevens (standaard), headers en standaardsysteemprompts voor elke provider. Definieert ook `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` en `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Laadt externe inloggegevens van `data/provider-credentials.json` en voegt deze samen met de hardgecodeerde standaardwaarden in `PROVIDERS`. Houdt geheimen buiten de broncontrole en behoudt achterwaartse compatibiliteit. | -| `providerModels.ts` | Centraal modelregister: brengt provideraliassen in kaart → model-ID's. Functies zoals `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Systeeminstructies geïnjecteerd in Codex-verzoeken (bewerkingsbeperkingen, sandbox-regels, goedkeuringsbeleid). | -| `defaultThinkingSignature.ts` | Standaard "denkende" handtekeningen voor Claude- en Gemini-modellen. | -| `ollamaModels.ts` | Schemadefinitie voor lokale Ollama-modellen (naam, grootte, familie, kwantisering). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Laadstroom van inloggegevens +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Executeurs (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Uitvoerders kapselen **providerspecifieke logica** in met behulp van het **Strategiepatroon**. Elke uitvoerder overschrijft indien nodig basismethoden. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| executeur | Aanbieder | Belangrijkste specialisaties | -| ---------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Samenvatting van de basis: URL-opbouw, headers, logica voor opnieuw proberen, vernieuwen van inloggegevens | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generieke OAuth-tokenvernieuwing voor standaardproviders | -| `antigravity.ts` | Google Cloud-code | Generatie van project-/sessie-ID's, fallback met meerdere URL's, aangepaste parsering van foutmeldingen ("reset na 2u7m23s") | -| `cursor.ts` | Cursor-IDE | **Meest complex**: SHA-256 checksum-authenticatie, Protobuf-verzoekcodering, binaire EventStream → Parsing van SSE-antwoorden | -| `codex.ts` | OpenAI-codex | Injecteert systeeminstructies, beheert denkniveaus, verwijdert niet-ondersteunde parameters | -| `gemini-cli.ts` | Google Gemini-CLI | Aangepaste URL maken (`streamGenerateContent`), Google OAuth-token vernieuwen | -| `github.ts` | GitHub-copiloot | Dubbel tokensysteem (GitHub OAuth + Copilot-token), VSCode-header die | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binaire parsing, AMZN-gebeurtenisframes, tokenschatting | -| `index.ts` | — | Fabriek: kaartprovidernaam → uitvoerderklasse, met standaard fallback | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Afhandelaars (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -De **orkestratielaag** — coördineert de vertaling, uitvoering, streaming en foutafhandeling. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Bestand | Doel | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Centrale orkestrator** (~600 lijnen). Verwerkt de volledige levenscyclus van verzoeken: formaatdetectie → vertaling → verzending van de uitvoerder → streaming/niet-streaming antwoord → tokenvernieuwing → foutafhandeling → gebruiksregistratie. | -| `responsesHandler.ts` | Adapter voor OpenAI's Responses API: converteert het antwoordformaat → Chatvoltooiingen → verzendt naar `chatCore` → converteert SSE terug naar het antwoordformaat. | -| `embeddings.ts` | Handler voor het genereren van inbedding: lost het inbeddingsmodel → provider op, verzendt naar de API van de provider, retourneert OpenAI-compatibele inbeddingsreactie. Ondersteunt 6+ providers. | -| `imageGeneration.ts` | Handler voor het genereren van afbeeldingen: lost beeldmodel → provider op, ondersteunt OpenAI-compatibele, Gemini-image (Antigravity) en fallback (Nebius) modi. Retourneert base64- of URL-afbeeldingen. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Aanvraaglevenscyclus (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Diensten (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Bedrijfslogica die de behandelaars en uitvoerders ondersteunt. +Business logic that supports the handlers and executors. -| Bestand | Doel | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Formaatdetectie** (`detectFormat`): analyseert de lichaamsstructuur van het verzoek om de formaten Claude/OpenAI/Gemini/Antigravity/Responses te identificeren (inclusief `max_tokens` heuristiek voor Claude). Ook: URL-opbouw, header-opbouw, normalisatie van denkconfiguraties. Ondersteunt `openai-compatible-*` en `anthropic-compatible-*` dynamische providers. | -| `model.ts` | Parseren van modeltekenreeksen (`claude/model-name` → `{provider: "claude", model: "model-name"}`), aliasresolutie met botsingsdetectie, invoeropschoning (weigert paddoorloop/controletekens) en modelinformatieresolutie met ondersteuning voor asynchrone aliasgetter. | -| `accountFallback.ts` | Afhandeling van snelheidslimieten: exponentiële uitstel (1s → 2s → 4s → max. 2min), beheer van accountcooldown, foutclassificatie (welke fouten een terugval veroorzaken versus niet). | -| `tokenRefresh.ts` | OAuth-tokenvernieuwing voor **elke provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Inclusief in-flight belofte-deduplicatiecache en opnieuw proberen met exponentiële uitstel. | -| `combo.ts` | **Combomodellen**: ketens van fallback-modellen. Als model A faalt met een fout die in aanmerking komt voor terugval, probeer dan model B, vervolgens C, enz. Retourneert werkelijke stroomopwaartse statuscodes. | -| `usage.ts` | Haalt quota/gebruiksgegevens op van provider-API's (GitHub Copilot-quota, Antigravity-modelquota, Codex-snelheidslimieten, uitsplitsingen van Kiro-gebruik, Claude-instellingen). | -| `accountSelector.ts` | Slimme accountselectie met score-algoritme: houdt rekening met prioriteit, gezondheidsstatus, round-robin-positie en cooldown-status om voor elk verzoek het optimale account te kiezen. | -| `contextManager.ts` | Beheer van de contextlevenscyclus van aanvragen: creëert en volgt contextobjecten per aanvraag met metagegevens (aanvraag-ID, tijdstempels, providerinformatie) voor foutopsporing en logboekregistratie. | -| `ipFilter.ts` | IP-gebaseerd toegangscontrole: ondersteunt de toelatingslijst- en blokkeerlijstmodi. Valideert client-IP aan de hand van geconfigureerde regels voordat API-aanvragen worden verwerkt. | -| `sessionManager.ts` | Sessie volgen met client-fingerprinting: volgt actieve sessies met behulp van gehashte client-ID's, bewaakt het aantal verzoeken en biedt sessiestatistieken. | -| `signatureCache.ts` | Op handtekeningen gebaseerde deduplicatiecache aanvragen: voorkomt dubbele verzoeken door handtekeningen van recente verzoeken in de cache op te slaan en in de cache opgeslagen antwoorden voor identieke verzoeken binnen een tijdsvenster te retourneren. | -| `systemPrompt.ts` | Globale injectie van systeemprompts: voegt een configureerbare systeemprompt toe aan alle verzoeken, waarbij de compatibiliteit per provider wordt afgehandeld. | -| `thinkingBudget.ts` | Budgetbeheer voor redeneringstokens: ondersteunt passthrough-, automatische (strip-thinking-configuratie), aangepaste (vast budget) en adaptieve (op complexiteit geschaalde) modi voor het controleren van denk-/redeneringstokens. | -| `wildcardRouter.ts` | Patroonroutering met jokertekenmodel: zet jokertekenpatronen (bijvoorbeeld `*/claude-*`) om in concrete provider/modelparen op basis van beschikbaarheid en prioriteit. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Ontdubbeling van tokenvernieuwing +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Combo-modelketen +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Vertaler (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -De **formaatvertaalmachine** gebruikt een zelfregistrerend plug-insysteem. +The **format translation engine** using a self-registering plugin system. -#### Architectuur +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Telefoonboek | Bestanden | Beschrijving | -| ------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 vertalers | Converteer verzoekteksten tussen formaten. Elk bestand registreert zichzelf via `register(from, to, fn)` bij het importeren. | -| `response/` | 7 vertalers | Converteer streamingantwoordbrokken tussen formaten. Verwerkt SSE-gebeurtenistypen, denkblokken, tooloproepen. | -| `helpers/` | 6 helpers | Gedeelde hulpprogramma's: `claudeHelper` (extractie van systeemprompts, denkconfiguratie), `geminiHelper` (toewijzing van onderdelen/inhoud), `openaiHelper` (formaatfiltering), `toolCallHelper` (ID genereren, injectie van ontbrekende antwoorden), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Vertaalmachine: `translateRequest()`, `translateResponse()`, staatsbeheer, register. | -| `formats.ts` | — | Formaatconstanten: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Sleutelontwerp: zelfregistrerende plug-ins +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Hulpprogramma's (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Bestand | Doel | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Opbouw van foutreacties (OpenAI-compatibel formaat), upstream-foutparsing, Antigravity-extractie van nieuwe pogingen uit foutmeldingen, SSE-foutstreaming. | -| `stream.ts` | **SSE Transform Stream** — de belangrijkste streamingpijplijn. Twee modi: `TRANSLATE` (vertaling in volledig formaat) en `PASSTHROUGH` (gebruik normaliseren + extraheren). Verwerkt chunkbuffering, gebruiksschatting en het bijhouden van de inhoudslengte. Encoder/decoder-instanties per stream vermijden een gedeelde status. | -| `streamHelpers.ts` | SSE-hulpprogramma's op laag niveau: `parseSSELine` (witruimtetolerant), `hasValuableContent` (filtert lege chunks voor OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (formaatbewuste SSE-serialisatie met opschoning `perf_metrics`). | -| `usageTracking.ts` | Extractie van tokengebruik uit elk formaat (Claude/OpenAI/Gemini/Responses), schatting met afzonderlijke tool/bericht-char-per-token-verhoudingen, buffertoevoeging (veiligheidsmarge van 2000 tokens), formaatspecifieke veldfiltering, consolelogboekregistratie met ANSI-kleuren. | -| `requestLogger.ts` | Op bestanden gebaseerde registratie van verzoeken (opt-in via `ENABLE_REQUEST_LOGS=true`). Creëert sessiemappen met genummerde bestanden: `1_req_client.json` → `7_res_client.txt`. Alle I/O is async (fire-and-forget). Maskert gevoelige headers. | -| `bypassHandler.ts` | Onderschept specifieke patronen van Claude CLI (titelextractie, opwarming, telling) en retourneert valse antwoorden zonder een provider te bellen. Ondersteunt zowel streaming als niet-streaming. Opzettelijk beperkt tot het Claude CLI-bereik. | -| `networkProxy.ts` | Bepaalt de uitgaande proxy-URL voor een bepaalde provider met voorrang: providerspecifieke configuratie → globale configuratie → omgevingsvariabelen (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Ondersteunt `NO_PROXY` uitsluitingen. Cachesconfiguratie voor 30s. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### SSE-streamingpijplijn +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Verzoek Loggersessiestructuur +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Applicatielaag (`src/`) +### 4.7 Application Layer (`src/`) -| Telefoonboek | Doel | -| ------------- | --------------------------------------------------------------------------------- | -| `src/app/` | Web-UI, API-routes, Express-middleware, OAuth-callback-handlers | -| `src/lib/` | Databasetoegang (`localDb.ts`, `usageDb.ts`), authenticatie, gedeeld | -| `src/mitm/` | Man-in-the-middle-proxyhulpprogramma's voor het onderscheppen van providerverkeer | -| `src/models/` | Definities van databasemodellen | -| `src/shared/` | Wrappers rond open-sse-functies (provider, stream, fout, etc.) | -| `src/sse/` | SSE-eindpunthandlers die de open-sse-bibliotheek verbinden met Express-routes | -| `src/store/` | Beheer van applicatiestatus | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Opmerkelijke API-routes +#### Notable API Routes -| Route | Methoden | Doel | -| --------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | KRIJGEN/POST/VERWIJDEREN | CRUD voor maatwerkmodellen per aanbieder | -| `/api/models/catalog` | KRIJG | Geaggregeerde catalogus van alle modellen (chat, insluiten, afbeelding, aangepast) gegroepeerd op provider | -| `/api/settings/proxy` | KRIJGEN/ZET/VERWIJDEREN | Hiërarchische uitgaande proxyconfiguratie (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Valideert proxy-connectiviteit en retourneert openbare IP/latentie | -| `/v1/providers/[provider]/chat/completions` | POST | Specifieke chatafrondingen per provider met modelvalidatie | -| `/v1/providers/[provider]/embeddings` | POST | Toegewijde inbedding per provider met modelvalidatie | -| `/v1/providers/[provider]/images/generations` | POST | Specifieke generatie van afbeeldingen per provider met modelvalidatie | -| `/api/settings/ip-filter` | KRIJG/ZET | Beheer van IP-toelatingslijsten/blokkeerlijsten | -| `/api/settings/thinking-budget` | KRIJG/ZET | Redeneren token budgetconfiguratie (passthrough/auto/aangepast/adaptief) | -| `/api/settings/system-prompt` | KRIJG/ZET | Wereldwijde systeempromptinjectie voor alle verzoeken | -| `/api/sessions` | KRIJG | Actieve sessietracking en statistieken | -| `/api/rate-limits` | KRIJG | Status van tarieflimiet per account | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Belangrijke ontwerppatronen +## 5. Key Design Patterns -### 5.1 Hub-and-spoke-vertaling +### 5.1 Hub-and-Spoke Translation -Alle formaten worden vertaald via het **OpenAI-formaat als hub**. Voor het toevoegen van een nieuwe provider is slechts **één paar** vertalers nodig (van/naar OpenAI), niet N-paren. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Strategiepatroon voor de uitvoerder +### 5.2 Executor Strategy Pattern -Elke provider heeft een speciale uitvoerderklasse die overerft van `BaseExecutor`. De fabriek in `executors/index.ts` selecteert tijdens runtime de juiste. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Zelfregistrerend plug-insysteem +### 5.3 Self-Registering Plugin System -Vertalermodules registreren zichzelf bij het importeren via `register()`. Als u een nieuwe vertaler toevoegt, maakt u eenvoudigweg een bestand aan en importeert u dit. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Accountterugval met exponentiële uitstel +### 5.4 Account Fallback with Exponential Backoff -Wanneer een provider 429/401/500 retourneert, kan het systeem overschakelen naar het volgende account, waarbij exponentiële cooldowns worden toegepast (1s → 2s → 4s → max. 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 combo-modelketens +### 5.5 Combo Model Chains -Een "combo" groepeert meerdere `provider/model` strings. Als de eerste mislukt, wordt automatisch teruggevallen op de volgende. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Stateful streaming-vertaling +### 5.6 Stateful Streaming Translation -Reactievertaling handhaaft de status van SSE-brokken (tracking van denkblokken, accumulatie van tooloproepen, indexering van inhoudsblokken) via het `initState()`-mechanisme. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Gebruiksveiligheidsbuffer +### 5.7 Usage Safety Buffer -Er wordt een buffer van 2000 token toegevoegd aan het gerapporteerde gebruik om te voorkomen dat clients de limieten van het contextvenster bereiken als gevolg van overhead van systeemprompts en formaatvertaling. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Ondersteunde formaten +## 6. Supported Formats -| Formaat | Richting | Identificatie | -| ------------------------ | ----------- | ------------------ | -| OpenAI Chat-voltooiingen | bron + doel | `openai` | -| OpenAI-reacties-API | bron + doel | `openai-responses` | -| Antropische Claude | bron + doel | `claude` | -| Google Tweeling | bron + doel | `gemini` | -| Google Gemini-CLI | alleen doel | `gemini-cli` | -| Antizwaartekracht | bron + doel | `antigravity` | -| AWS Kiro | alleen doel | `kiro` | -| Cursor | alleen doel | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Ondersteunde providers +## 7. Supported Providers -| Aanbieder | Verificatiemethode | executeur | Belangrijkste opmerkingen | -| ------------------------ | ----------------------- | ----------------- | -------------------------------------------------------------------- | -| Antropische Claude | API-sleutel of OAuth | Standaard | Gebruikt `x-api-key` koptekst | -| Google Tweeling | API-sleutel of OAuth | Standaard | Gebruikt `x-goog-api-key` koptekst | -| Google Gemini-CLI | OAuth | GeminiCLI | Gebruikt `streamGenerateContent` eindpunt | -| Antizwaartekracht | OAuth | Antizwaartekracht | Terugval op meerdere URL's, aangepaste parsering van nieuwe pogingen | -| Open AI | API-sleutel | Standaard | Standaard Bearer-authenticatie | -| Codex | OAuth | Codex | Injecteert systeeminstructies, beheert het denken | -| GitHub-copiloot | OAuth + Copilot-token | Github | Dubbel token, VSCode-header die | -| Kiro (AWS) | AWS SSO OIDC of sociaal | Kiro | Binaire EventStream-parsering | -| Cursor-IDE | Controlesomverificatie | Cursor | Protobuf-codering, SHA-256-controlesommen | -| Qwen | OAuth | Standaard | Standaardauthenticatie | -| iFlow | OAuth (basis + drager) | Standaard | Dubbele auth-header | -| OpenRouter | API-sleutel | Standaard | Standaard Bearer-authenticatie | -| GLM, Kimi, MiniMax | API-sleutel | Standaard | Claude-compatibel, gebruik `x-api-key` | -| `openai-compatible-*` | API-sleutel | Standaard | Dynamisch: elk OpenAI-compatibel eindpunt | -| `anthropic-compatible-*` | API-sleutel | Standaard | Dynamisch: elk Claude-compatibel eindpunt | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Samenvatting van de gegevensstroom +## 8. Data Flow Summary -### Streamingverzoek +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Niet-streamingverzoek +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Bypassstroom (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/nl/FEATURES.md b/docs/i18n/nl/FEATURES.md index 73fa29a5c4..82cc73b67b 100644 --- a/docs/i18n/nl/FEATURES.md +++ b/docs/i18n/nl/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Galerij met dashboardfuncties +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Visuele gids voor elke sectie van het OmniRoute-dashboard. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Aanbieders +## 🔌 Providers -Beheer AI-providerverbindingen: OAuth-providers (Claude Code, Codex, Gemini CLI), API-sleutelproviders (Groq, DeepSeek, OpenRouter) en gratis providers (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨Combo's +## 🎨 Combos -Creëer modelrouteringscombinaties met 6 strategieën: eerst vullen, round-robin, macht van twee keuzes, willekeurig, minst gebruikt en kostengeoptimaliseerd. Elke combo koppelt meerdere modellen met automatische terugval. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Analyse +## 📊 Analytics -Uitgebreide gebruiksanalyses met tokenverbruik, kostenramingen, activiteiten-heatmaps, wekelijkse distributiegrafieken en uitsplitsingen per provider. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥Systeemgezondheid +## 🏥 System Health -Realtime monitoring: uptime, geheugen, versie, latentiepercentielen (p50/p95/p99), cachestatistieken en status van stroomonderbrekers van de provider. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Vertalerspeeltuin +## 🔧 Translator Playground -Vier modi voor het debuggen van API-vertalingen: **Playground** (formaatconverter), **Chat Tester** (live verzoeken), **Test Bench** (batchtests) en **Live Monitor** (realtime stream). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Instellingen +## 🎮 Model Playground _(v2.0.9+)_ -Algemene instellingen, systeemopslag, back-upbeheer (database exporteren/importeren), uiterlijk (donker/licht-modus), beveiliging (inclusief API-eindpuntbescherming en aangepaste providerblokkering), routing (model aliases, background task degradation), veerkracht en geavanceerde configuratie. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI-hulpmiddelen +## 🔧 CLI Tools -Configuratie met één klik voor AI-coderingstools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code en Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Logboeken aanvragen +## 🤖 CLI Agents _(v2.0.11+)_ -Realtime logboekregistratie van verzoeken met filtering op provider, model, account en API-sleutel. Toont statuscodes, tokengebruik, latentie en responsdetails. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API-eindpunt +## 🌐 API Endpoint -Uw uniforme API-eindpunt met uitsplitsing van de mogelijkheden: chatvoltooiingen, insluitingen, het genereren van afbeeldingen, herrangschikking, audiotranscriptie en geregistreerde API-sleutels. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/nl/TROUBLESHOOTING.md b/docs/i18n/nl/TROUBLESHOOTING.md index b1ec3b4f95..120092d63c 100644 --- a/docs/i18n/nl/TROUBLESHOOTING.md +++ b/docs/i18n/nl/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Problemen oplossen +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Veelvoorkomende problemen en oplossingen voor OmniRoute. +Common problems and solutions for OmniRoute. --- -## Snelle oplossingen +## Quick Fixes -| Probleem | Oplossing | -| ----------------------------------- | ----------------------------------------------------------------------- | ---------------- | -| Eerste login werkt niet | Controleer `INITIAL_PASSWORD` in `.env` (standaard: `123456`) | -| Dashboard opent op verkeerde poort | Stel `PORT=20128` en `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | in | -| Geen verzoeklogboeken onder `logs/` | Stel `ENABLE_REQUEST_LOGS=true` | in | -| EACCES: toestemming geweigerd | Stel `DATA_DIR=/path/to/writable/dir` in om `~/.omniroute` | te overschrijven | -| Routeringsstrategie bespaart niet | Update naar v1.4.11+ (Zod-schemafix voor persistentie van instellingen) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Problemen met providers +## Provider Issues -### "Taalmodel heeft geen berichten geleverd" +### "Language model did not provide messages" -**Oorzaak:** Providerquotum is opgebruikt. +**Cause:** Provider quota exhausted. -**Opgelost:** +**Fix:** -1. Controleer de dashboardquotatracker -2. Gebruik een combo met fallback-lagen -3. Schakel over naar het goedkopere/gratis niveau +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Snelheidslimiet +### Rate Limiting -**Oorzaak:** Abonnementsquota zijn opgebruikt. +**Cause:** Subscription quota exhausted. -**Opgelost:** +**Fix:** -- Terugval toevoegen: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Gebruik GLM/MiniMax als goedkope back-up +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth-token verlopen +### OAuth Token Expired -OmniRoute vernieuwt tokens automatisch. Als de problemen aanhouden: +OmniRoute auto-refreshes tokens. If issues persist: -1. Dashboard → Provider → Opnieuw verbinden -2. Verwijder de providerverbinding en voeg deze opnieuw toe +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Cloudproblemen +## Cloud Issues -### Cloudsynchronisatiefouten +### Cloud Sync Errors -1. Controleer of `BASE_URL` verwijst naar uw actieve exemplaar (bijvoorbeeld `http://localhost:20128`) -2. Controleer of `CLOUD_URL` verwijst naar uw cloudeindpunt (bijvoorbeeld `https://omniroute.dev`) -3. Zorg ervoor dat de `NEXT_PUBLIC_*`-waarden overeenkomen met de waarden op de server +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Wolk `stream=false` Retourneert 500 +### Cloud `stream=false` Returns 500 -**Symptoom:** `Unexpected token 'd'...` op cloudeindpunt voor niet-streaming oproepen. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Oorzaak:** Upstream retourneert SSE-payload terwijl de client JSON verwacht. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Oplossing:** Gebruik `stream=true` voor directe cloudoproepen. Lokale runtime omvat SSE → JSON-fallback. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud zegt verbonden maar "Ongeldige API-sleutel" +### Cloud Says Connected but "Invalid API key" -1. Maak een nieuwe sleutel vanaf het lokale dashboard (`/api/keys`) -2. Voer cloudsynchronisatie uit: Schakel Cloud in → Nu synchroniseren -3. Oude/niet-gesynchroniseerde sleutels kunnen nog steeds `401` retourneren in de cloud +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Docker-problemen +## Docker Issues -### CLI-tool geeft aan dat deze niet is geïnstalleerd +### CLI Tool Shows Not Installed -1. Controleer runtimevelden: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Voor draagbare modus: gebruik afbeeldingsdoel `runner-cli` (gebundelde CLI's) -3. Voor de host-aankoppelmodus: stel `CLI_EXTRA_PATHS` in en koppel de hostbin-map aan als alleen-lezen -4. Als `installed=true` en `runnable=false`: binair bestand is gevonden maar de statuscheck is mislukt +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Snelle runtime-validatie +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Kostenproblemen +## Cost Issues -### Hoge kosten +### High Costs -1. Controleer gebruiksstatistieken in Dashboard → Gebruik -2. Schakel het primaire model over naar GLM/MiniMax -3. Gebruik de gratis laag (Gemini CLI, iFlow) voor niet-kritieke taken -4. Stel kostenbudgetten per API-sleutel in: Dashboard → API-sleutels → Budget +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Foutopsporing +## Debugging -### Verzoeklogboeken inschakelen +### Enable Request Logs -Stel `ENABLE_REQUEST_LOGS=true` in uw `.env` bestand in. Logboeken verschijnen onder de map `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Controleer de gezondheid van de provider +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Runtime-opslag +### Runtime Storage -- Hoofdstatus: `${DATA_DIR}/db.json` (providers, combo's, aliassen, sleutels, instellingen) -- Gebruik: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Logboeken aanvragen: `/logs/...` (wanneer `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Problemen met stroomonderbrekers +## Circuit Breaker Issues -### Provider zit vast in OPEN-status +### Provider stuck in OPEN state -Wanneer de stroomonderbreker van een provider OPEN is, worden verzoeken geblokkeerd totdat de cooldown is verstreken. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Opgelost:** +**Fix:** -1. Ga naar **Dashboard → Instellingen → Veerkracht** -2. Controleer de stroomonderbrekerkaart van de betreffende provider -3. Klik op **Alles resetten** om alle onderbrekers te wissen, of wacht tot de cooldown is verstreken -4. Controleer of de provider daadwerkelijk beschikbaar is voordat u reset +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### De provider schakelt de stroomonderbreker steeds uit +### Provider keeps tripping the circuit breaker -Als een aanbieder herhaaldelijk in de OPEN-status komt: +If a provider repeatedly enters OPEN state: -1. Controleer **Dashboard → Gezondheid → Providergezondheid** voor het foutpatroon -2. Ga naar **Instellingen → Veerkracht → Providerprofielen** en verhoog de foutdrempel -3. Controleer of de provider de API-limieten heeft gewijzigd of herauthenticatie vereist -4. Controleer latentie-telemetrie: hoge latentie kan op time-outs gebaseerde fouten veroorzaken +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problemen met audiotranscriptie +## Audio Transcription Issues -### Fout 'Niet-ondersteund model' +### "Unsupported model" error -- Zorg ervoor dat u het juiste voorvoegsel gebruikt: `deepgram/nova-3` of `assemblyai/best` -- Controleer of de provider is verbonden in **Dashboard → Providers** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Transcriptie is leeg of mislukt +### Transcription returns empty or fails -- Controleer ondersteunde audioformaten: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Controleer of de bestandsgrootte binnen de limieten van de provider ligt (doorgaans < 25 MB) -- Controleer de geldigheid van de API-sleutel van de provider op de providerkaart +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Foutopsporing bij vertalers +## Translator Debugging -Gebruik **Dashboard → Vertaler** om problemen met de vertaling van formaten op te lossen: +Use **Dashboard → Translator** to debug format translation issues: -| Modus | Wanneer gebruiken | -| --------------- | ---------------------------------------------------------------------------------------------------------- | -| **Speeltuin** | Vergelijk invoer-/uitvoerformaten naast elkaar - plak een mislukt verzoek om te zien hoe het zich vertaalt | -| **Chattester** | Verzend live berichten en inspecteer de volledige payload van verzoeken/antwoorden, inclusief headers | -| **Proefbank** | Voer batchtests uit voor indelingscombinaties om te ontdekken welke vertalingen niet werken | -| **Livemonitor** | Bekijk de realtime aanvraagstroom om intermitterende vertaalproblemen op te sporen | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Veelvoorkomende formaatproblemen +### Common format issues -- **Thinking-tags verschijnen niet** — Controleer of de doelaanbieder het denken en de instelling van het denkbudget ondersteunt -- **Tooloproepen vervallen** — Bij sommige formaatvertalingen kunnen niet-ondersteunde velden worden verwijderd; verifiëren in Speeltuinmodus -- **Systeemprompt ontbreekt** — Claude en Gemini behandelen de systeemprompts anders; controleer de vertalingsuitvoer -- **SDK retourneert onbewerkte tekenreeks in plaats van object** — Opgelost in v1.1.0: respons sanitizer verwijdert nu niet-standaard velden (`x_groq`, `usage_breakdown`, etc.) die OpenAI SDK Pydantic-validatiefouten veroorzaken -- **GLM/ERNIE weigert de rol `system`** — Opgelost in v1.1.0: de rolnormalizer voegt systeemberichten automatisch samen met gebruikersberichten voor incompatibele modellen -- **`developer` rol niet herkend** — Opgelost in v1.1.0: automatisch geconverteerd naar `system` voor niet-OpenAI-providers -- **`json_schema` werkt niet met Gemini** — Opgelost in v1.1.0: `response_format` is nu geconverteerd naar Gemini's `responseMimeType` + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Veerkrachtinstellingen +## Resilience Settings -### Automatische snelheidslimiet wordt niet geactiveerd +### Auto rate-limit not triggering -- Automatische tarieflimiet is alleen van toepassing op API-sleutelproviders (niet op OAuth/abonnement) -- Controleer of bij Instellingen → Veerkracht → Providerprofielen\*\* automatische tarieflimiet is ingeschakeld -- Controleer of de provider `429` statuscodes of `Retry-After` headers retourneert +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Exponentiële uitstel afstemmen +### Tuning exponential backoff -Providerprofielen ondersteunen deze instellingen: +Provider profiles support these settings: -- **Basisvertraging** — Initiële wachttijd na eerste storing (standaard: 1s) -- **Max. vertraging** — Maximale wachttijdlimiet (standaard: 30s) -- **Vermenigvuldiger** — Hoeveel vertraging per opeenvolgende fout moet worden vergroot (standaard: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Anti-donderende kudde +### Anti-thundering herd -Wanneer veel gelijktijdige verzoeken een provider met een beperkte snelheid bereiken, gebruikt OmniRoute mutex + automatische snelheidsbeperking om verzoeken te serialiseren en trapsgewijze fouten te voorkomen. Dit gebeurt automatisch voor API-sleutelproviders. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Zit je nog steeds vast? +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub-problemen**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architectuur**: zie [link](ARCHITECTURE.md) voor interne details -- **API-referentie**: zie [link](API_REFERENCE.md) voor alle eindpunten -- **Gezondheidsdashboard**: controleer **Dashboard → Gezondheid** voor de realtime systeemstatus -- **Vertaler**: gebruik **Dashboard → Vertaler** om formaatproblemen op te lossen +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/nl/USER_GUIDE.md b/docs/i18n/nl/USER_GUIDE.md index c7e8c33c0c..5a043224df 100644 --- a/docs/i18n/nl/USER_GUIDE.md +++ b/docs/i18n/nl/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Gebruikershandleiding +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Volledige gids voor het configureren van providers, het maken van combo's, het integreren van CLI-tools en het implementeren van OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Inhoudsopgave +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Volledige gids voor het configureren van providers, het maken van combo's, het i --- -## 💰 Prijzen in één oogopslag +## 💰 Pricing at a Glance -| Niveau | Aanbieder | Kosten | Quotum opnieuw instellen | Beste voor | -| ------------------ | ----------------- | ------------------- | ------------------------ | --------------------------- | -| **💳 ABONNEMENT** | Claude Code (Pro) | $ 20/maand | 5u + wekelijks | Al geabonneerd | -| | Codex (Plus/Pro) | $ 20-200/maand | 5u + wekelijks | OpenAI-gebruikers | -| | Tweeling CLI | **GRATIS** | 180K/maand + 1K/dag | Iedereen! | -| | GitHub-copiloot | $ 10-19/maand | Maandelijks | GitHub-gebruikers | -| **🔑 API-SLEUTEL** | DeepSeek | Betalen per gebruik | Geen | Goedkoop redeneren | -| | Groq | Betalen per gebruik | Geen | Ultrasnelle gevolgtrekking | -| | xAI (Grok) | Betalen per gebruik | Geen | Grok 4 redenering | -| | Mistral | Betalen per gebruik | Geen | Door de EU gehoste modellen | -| | Verbijstering | Betalen per gebruik | Geen | Zoek-uitgebreid | -| | Samen AI | Betalen per gebruik | Geen | Open source-modellen | -| | Vuurwerk AI | Betalen per gebruik | Geen | Snelle FLUX-afbeeldingen | -| | Hersenen | Betalen per gebruik | Geen | Snelheid op wafelschaal | -| | Cohier | Betalen per gebruik | Geen | Commando R+ RAG | -| | NVIDIA NIM | Betalen per gebruik | Geen | Enterprise-modellen | -| **💰GOEDKOOP** | GLM-4.7 | $ 0,6/1 miljoen | Dagelijks 10.00 uur | Budgetback-up | -| | MiniMax M2.1 | $ 0,2/1 miljoen | 5-uurs rollen | Goedkoopste optie | -| | Kimi K2 | $ 9/maand plat | 10 miljoen tokens/maand | Voorspelbare kosten | -| **🆓 GRATIS** | iFlow | $0 | Onbeperkt | 8 modellen gratis | -| | Qwen | $0 | Onbeperkt | 3 modellen gratis | -| | Kiro | $0 | Onbeperkt | Claude vrij | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Pro-tip:** Begin met Gemini CLI (180K gratis/maand) + iFlow (onbeperkt gratis) combo = $ 0 kosten! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Gebruiksscenario's +## 🎯 Use Cases -### Geval 1: "Ik heb een Claude Pro-abonnement" +### Case 1: "I have Claude Pro subscription" -**Probleem:** Quotum verloopt ongebruikt, snelheidslimieten tijdens intensief coderen +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Geval 2: "Ik wil geen kosten" +### Case 2: "I want zero cost" -**Probleem:** Ik kan geen abonnementen betalen, heb betrouwbare AI-codering nodig +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Geval 3: "Ik heb 24/7 codering nodig, geen onderbrekingen" +### Case 3: "I need 24/7 coding, no interruptions" -**Probleem:** Deadlines, downtime is niet mogelijk +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Case 4: "Ik wil GRATIS AI in OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Probleem:** AI-assistent nodig in berichtenapps, geheel gratis +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Providerconfiguratie +## 📖 Provider Setup -### 🔐 Abonnementsaanbieders +### 🔐 Subscription Providers -#### Claude-code (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Pro-tip:** Gebruik Opus voor complexe taken, Sonnet voor snelheid. OmniRoute houdt quota bij per model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (GRATIS 180K/maand!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Beste waarde:** Enorm gratis niveau! Gebruik dit vóór betaalde niveaus. +**Best Value:** Huge free tier! Use this before paid tiers. -#### GitHub-copiloot +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Goedkope aanbieders +### 💰 Cheap Providers -#### GLM-4.7 (dagelijkse reset, $0,6/1 miljoen) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Aanmelden: [Zhipu AI](https://open.bigmodel.cn/) -2. Haal de API-sleutel op uit het Coderingsplan -3. Dashboard → API-sleutel toevoegen: Provider: `glm`, API-sleutel: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Gebruik:** `glm/glm-4.7` — **Pro-tip:** Codeerplan biedt 3× quota tegen 1/7 kosten! Dagelijks resetten om 10:00 uur. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 uur resetten, $0,20/1M) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Aanmelden: [MiniMax](https://www.minimax.io/) -2. API-sleutel ophalen → Dashboard → API-sleutel toevoegen +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Gebruik:** `minimax/MiniMax-M2.1` — **Pro-tip:** Goedkoopste optie voor lange context (1 miljoen tokens)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/maand vast) +#### Kimi K2 ($9/month flat) -1. Abonneer je: [Moonshot AI](https://platform.moonshot.ai/) -2. API-sleutel ophalen → Dashboard → API-sleutel toevoegen +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Gebruik:** `kimi/kimi-latest` — **Pro-tip:** Vaste $ 9/maand voor 10 miljoen tokens = $ 0,90/1 miljoen effectieve kosten! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 GRATIS Aanbieders +### 🆓 FREE Providers -#### iFlow (8 GRATIS modellen) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 GRATIS modellen) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRATIS) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨Combo's +## 🎨 Combos -### Voorbeeld 1: Maximaliseer abonnement → Goedkope back-up +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Voorbeeld 2: Alleen gratis (geen kosten) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI-integratie +## 🔧 CLI Integration -### Cursor-IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Claude-code +### Claude Code -Bewerk `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Bewerk `~/.claude/config.json`: } ``` -### Codex-CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -279,9 +279,9 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### Open Klauw +### OpenClaw -Bewerk `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Bewerk `~/.openclaw/openclaw.json`: } ``` -**Of gebruik Dashboard:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Doorgaan / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Implementatie +## 🚀 Deployment -### VPS-implementatie +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Voor de host-geïntegreerde modus met CLI-binaire bestanden raadpleegt u de Docker-sectie in de hoofddocumentatie. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Omgevingsvariabelen +### Environment Variables -| Variabel | Standaard | Beschrijving | -| --------------------- | ------------------------------------ | --------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT-ondertekeningsgeheim (**productiewijziging**) | -| `INITIAL_PASSWORD` | `123456` | Wachtwoord voor eerste aanmelding | -| `DATA_DIR` | `~/.omniroute` | Gegevensmap (db, gebruik, logs) | -| `PORT` | standaard raamwerk | Servicepoort (`20128` in voorbeelden) | -| `HOSTNAME` | standaard raamwerk | Bind host (Docker is standaard ingesteld op `0.0.0.0`) | -| `NODE_ENV` | runtime-standaard | Stel `production` in voor implementatie | -| `BASE_URL` | `http://localhost:20128` | Interne basis-URL aan serverzijde | -| `CLOUD_URL` | `https://omniroute.dev` | Basis-URL van cloudsynchronisatie-eindpunt | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC-geheim voor gegenereerde API-sleutels | -| `REQUIRE_API_KEY` | `false` | Bearer API-sleutel afdwingen op `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Schakelt verzoek-/antwoordlogboeken in | -| `AUTH_COOKIE_SECURE` | `false` | Forceer `Secure` auth-cookie (achter HTTPS reverse proxy) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Zie [README](../README.md) voor de volledige referentie van de omgevingsvariabelen. +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Beschikbare modellen +## 📊 Available Models
-Bekijk alle beschikbare modellen +View all available models -**Claude-code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**GitHub-copiloot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — $ 0,6/1 miljoen: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $ 0,2/1 miljoen: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,15 +460,15 @@ Zie [README](../README.md) voor de volledige referentie van de omgevingsvariabel **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Verbijstering (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Samen AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Vuurwerk AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Cerebra's (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Samenhang (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Zie [README](../README.md) voor de volledige referentie van de omgevingsvariabel --- -## 🧩 Geavanceerde functies +## 🧩 Advanced Features -### Aangepaste modellen +### Custom Models -Voeg elke model-ID toe aan elke provider zonder te wachten op een app-update: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Of gebruik Dashboard: **Aanbieders → [Aanbieder] → Aangepaste modellen**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Speciale providerroutes +### Dedicated Provider Routes -Routeer verzoeken rechtstreeks naar een specifieke provider met modelvalidatie: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Het providervoorvoegsel wordt automatisch toegevoegd als het ontbreekt. Niet-overeenkomende modellen retourneren `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Netwerkproxyconfiguratie +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Voorrang:** Sleutelspecifiek → Combospecifiek → Providerspecifiek → Globaal → Omgeving. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### Modelcatalogus-API +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Retourneert modellen gegroepeerd op provider met typen (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Cloudsynchronisatie +### Cloud Sync -- Synchroniseer providers, combo's en instellingen op verschillende apparaten -- Automatische achtergrondsynchronisatie met time-out + fail-fast -- Geef de voorkeur aan server-side `BASE_URL`/`CLOUD_URL` in productie +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (Fase 9) +### LLM Gateway Intelligence (Phase 9) -- **Semantische cache** — Niet-streaming automatisch cachen, temperatuur=0 reacties (omzeilen met `X-OmniRoute-No-Cache: true`) -- **Request Idempotency** — Ontdubbelt verzoeken binnen 5 seconden via `Idempotency-Key` of `X-Request-Id` header -- **Voortgang bijhouden** — Meld u aan voor SSE `event: progress`-gebeurtenissen via de `X-OmniRoute-Progress: true` header +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Vertalerspeeltuin +### Translator Playground -Toegang via **Dashboard → Vertaler**. Debug en visualiseer hoe OmniRoute API-verzoeken tussen providers vertaalt. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Modus | Doel | -| --------------- | ----------------------------------------------------------------------------------------------------- | -| **Speeltuin** | Selecteer bron-/doelformaten, plak een verzoek en bekijk direct de vertaalde uitvoer | -| **Chattester** | Stuur livechatberichten via de proxy en inspecteer de volledige aanvraag/antwoordcyclus | -| **Proefbank** | Voer batchtests uit voor meerdere formaatcombinaties om de juistheid van de vertalingen te verifiëren | -| **Livemonitor** | Bekijk realtime vertalingen terwijl verzoeken via de proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Gebruiksscenario's:** +**Use cases:** -- Debug waarom een specifieke client/provider-combinatie mislukt -- Controleer of denktags, tooloproepen en systeemprompts correct worden vertaald -- Vergelijk formaatverschillen tussen OpenAI-, Claude-, Gemini- en Responses API-formaten +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Routeringsstrategieën +### Routing Strategies -Configureer via **Dashboard → Instellingen → Routing**. +Configure via **Dashboard → Settings → Routing**. -| Strategie | Beschrijving | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| **Eerst invullen** | Gebruikt accounts in volgorde van prioriteit: het primaire account handelt alle verzoeken af ​​totdat deze niet meer beschikbaar zijn | -| **Ronde Robin** | Bladert door alle accounts met een configureerbare sticky limiet (standaard: 3 oproepen per account) | -| **P2C (Kracht van twee keuzes)** | Kiest 2 willekeurige accounts en routes naar de gezondere – balanceert de belasting met bewustzijn van de gezondheid | -| **Willekeurig** | Selecteert willekeurig een account voor elk verzoek met behulp van Fisher-Yates shuffle | -| **Minst gebruikt** | Routes naar het account met de oudste `lastUsedAt` tijdstempel, waardoor het verkeer gelijkmatig wordt verdeeld | -| **Kostengeoptimaliseerd** | Routes naar het account met de laagste prioriteitswaarde, geoptimaliseerd voor providers met de laagste kosten | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Wildcard-modelaliassen +#### Wildcard Model Aliases -Maak jokertekenpatronen om modelnamen opnieuw toe te wijzen: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Jokertekens ondersteunen `*` (willekeurige tekens) en `?` (enkel teken). +Wildcards support `*` (any characters) and `?` (single character). -#### Terugvalketens +#### Fallback Chains -Definieer globale fallback-ketens die op alle verzoeken van toepassing zijn: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Veerkracht en stroomonderbrekers +### Resilience & Circuit Breakers -Configureer via **Dashboard → Instellingen → Veerkracht**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementeert veerkracht op providerniveau met vier componenten: +OmniRoute implements provider-level resilience with four components: -1. **Providerprofielen** — Configuratie per provider voor: - - Foutdrempel (hoeveel fouten vóór opening) - - Cooldown-duur - - Snelheidslimietdetectiegevoeligheid - - Exponentiële uitstelparameters +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Bewerkbare tarieflimieten** — Standaardinstellingen op systeemniveau configureerbaar in het dashboard: - - **Verzoeken per minuut (RPM)** — Maximaal aantal verzoeken per minuut per account - - **Min. tijd tussen verzoeken** — Minimale pauze in milliseconden tussen verzoeken - - **Max. gelijktijdige verzoeken** — Maximaal gelijktijdige verzoeken per account - - Klik op **Bewerken** om te wijzigen en vervolgens op **Opslaan** of **Annuleren**. Waarden blijven behouden via de veerkracht-API. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** — Volgt storingen per provider en opent automatisch het circuit wanneer een drempel wordt bereikt: - - **GESLOTEN** (Gezond) — Verzoeken stromen normaal door - - **OPEN** — Provider is tijdelijk geblokkeerd na herhaalde fouten - - **HALF_OPEN** — Testen of de provider is hersteld +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Beleid en vergrendelde identificatiegegevens** — Toont de status van de stroomonderbreker en vergrendelde identificatiegegevens met de mogelijkheid tot geforceerd ontgrendelen. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Automatische detectie van tarieflimiet** — Controleert de headers `429` en `Retry-After` om proactief te voorkomen dat de tarieflimieten van de provider worden overschreden. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Pro-tip:** Gebruik de knop **Alles resetten** om alle stroomonderbrekers en cooldowns te wissen wanneer een provider herstelt van een storing. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Database exporteren/importeren +### Database Export / Import -Beheer databaseback-ups in **Dashboard → Instellingen → Systeem en opslag**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Actie | Beschrijving | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Database exporteren** | Downloadt de huidige SQLite-database als een `.sqlite` bestand | -| **Alles exporteren (.tar.gz)** | Downloadt een volledig back-uparchief inclusief: database, instellingen, combo's, providerverbindingen (geen inloggegevens), API-sleutelmetagegevens | -| **Database importeren** | Upload een `.sqlite` bestand om de huidige database te vervangen. Er wordt automatisch een pre-importback-up gemaakt | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Importvalidatie:** Het geïmporteerde bestand wordt gevalideerd op integriteit (SQLite pragmacontrole), vereiste tabellen (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) en grootte (max. 100 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Gebruiksscenario's:** +**Use Cases:** -- Migreer OmniRoute tussen machines -- Maak externe back-ups voor noodherstel -- Deel configuraties tussen teamleden (alles exporteren → archief delen) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Instellingendashboard +### Settings Dashboard -De instellingenpagina is onderverdeeld in 5 tabbladen voor eenvoudige navigatie: +The settings page is organized into 5 tabs for easy navigation: -| Tabblad | Inhoud | -| --------------- | ------------------------------------------------------------------------------------------------------------------------- | -| **Beveiliging** | Login-/wachtwoordinstellingen, IP-toegangscontrole, API-authenticatie voor `/models` en providerblokkering | -| **Routing** | Globale routeringsstrategie (6 opties), wildcard-modelaliassen, fallback-ketens, combo-standaardwaarden | -| **Veerkracht** | Providerprofielen, bewerkbare tarieflimieten, status van stroomonderbrekers, beleid en vergrendelde identificatiegegevens | -| **AI** | Denken aan budgetconfiguratie, globale systeempromptinjectie, prompt cachestatistieken | -| **Geavanceerd** | Globale proxyconfiguratie (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Kosten- en budgetbeheer +### Costs & Budget Management -Toegang via **Dashboard → Kosten**. +Access via **Dashboard → Costs**. -| Tabblad | Doel | -| ------------- | ---------------------------------------------------------------------------------------------------------------- | -| **Begroting** | Stel bestedingslimieten per API-sleutel in met dagelijkse/wekelijkse/maandelijkse budgetten en realtime tracking | -| **Prijzen** | Bekijk en bewerk modelprijsgegevens — kosten per 1K input/output-tokens per provider | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Kosten bijhouden:** Bij elk verzoek wordt het tokengebruik geregistreerd en worden de kosten berekend met behulp van de prijstabel. Bekijk de uitsplitsingen in **Dashboard → Gebruik** per provider, model en API-sleutel. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Audiotranscriptie +### Audio Transcription -OmniRoute ondersteunt audiotranscriptie via het OpenAI-compatibele eindpunt: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Beschikbare providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Ondersteunde audioformaten: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Combo-balanceringsstrategieën +### Combo Balancing Strategies -Configureer de balans per combo in **Dashboard → Combo's → Maken/bewerken → Strategie**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategie | Beschrijving | -| ------------------------- | ----------------------------------------------------------------------------------- | -| **Round-Robin** | Roteert opeenvolgend door modellen | -| **Prioriteit** | Probeert altijd het eerste model; valt alleen terug op fouten | -| **Willekeurig** | Kiest voor elk verzoek een willekeurig model uit de combo | -| **Gewogen** | Routes proportioneel op basis van toegekende gewichten per model | -| **Minst gebruikt** | Routes naar het model met de minste recente verzoeken (gebruikt combo-statistieken) | -| **Kostengeoptimaliseerd** | Routes naar het goedkoopste beschikbare model (gebruikt prijstabel) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Algemene combo-standaardinstellingen kunnen worden ingesteld in **Dashboard → Instellingen → Routing → Combo-standaardwaarden**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Gezondheidsdashboard +### Health Dashboard -Toegang via **Dashboard → Gezondheid**. Realtime overzicht van de systeemstatus met 6 kaarten: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Kaart | Wat het laat zien | -| --------------------------- | -------------------------------------------------------------------------- | -| **Systeemstatus** | Uptime, versie, geheugengebruik, datadirectory | -| **Provider Gezondheid** | Status stroomonderbreker per provider (gesloten/open/halfopen) | -| **Tarieflimieten** | Actieve afkoelperiodes voor tarieflimieten per account met resterende tijd | -| **Actieve vergrendelingen** | Providers tijdelijk geblokkeerd door het lockoutbeleid | -| **Handtekeningcache** | Deduplicatiecachestatistieken (actieve sleutels, trefpercentage) | -| **Latentietelemetrie** | p50/p95/p99-latentieaggregatie per provider | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Pro-tip:** De Gezondheidspagina wordt elke 10 seconden automatisch vernieuwd. Gebruik de stroomonderbrekerkaart om te identificeren welke providers problemen ondervinden. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/no/API_REFERENCE.md b/docs/i18n/no/API_REFERENCE.md index 34267f6e65..b795722c11 100644 --- a/docs/i18n/no/API_REFERENCE.md +++ b/docs/i18n/no/API_REFERENCE.md @@ -1,12 +1,12 @@ -# API-referanse +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Fullstendig referanse for alle OmniRoute API-endepunkter. +Complete reference for all OmniRoute API endpoints. --- -## Innholdsfortegnelse +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Fullstendig referanse for alle OmniRoute API-endepunkter. --- -## Chatfullføringer +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Egendefinerte topptekster +### Custom Headers -| Overskrift | Retning | Beskrivelse | -| ------------------------ | ----------- | --------------------------------------- | -| `X-OmniRoute-No-Cache` | Forespørsel | Sett til `true` for å omgå cache | -| `X-OmniRoute-Progress` | Forespørsel | Sett til `true` for fremdriftshendelser | -| `Idempotency-Key` | Forespørsel | Dedup-nøkkel (5s-vindu) | -| `X-Request-Id` | Forespørsel | Alternativ dedup-nøkkel | -| `X-OmniRoute-Cache` | Svar | `HIT` eller `MISS` (ikke-streaming) | -| `X-OmniRoute-Idempotent` | Svar | `true` hvis deduplisert | -| `X-OmniRoute-Progress` | Svar | `enabled` hvis fremdriftssporing på | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Innebygginger +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Tilgjengelige leverandører: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Bildegenerering +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Tilgjengelige leverandører: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Liste over modeller +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Kompatibilitetsendepunkter +## Compatibility Endpoints -| Metode | Sti | Format | -| ------- | --------------------------- | ---------------------- | -| INNLEGG | `/v1/chat/completions` | OpenAI | -| INNLEGG | `/v1/messages` | Antropisk | -| INNLEGG | `/v1/responses` | OpenAI-svar | -| INNLEGG | `/v1/embeddings` | OpenAI | -| INNLEGG | `/v1/images/generations` | OpenAI | -| FÅ | `/v1/models` | OpenAI | -| INNLEGG | `/v1/messages/count_tokens` | Antropisk | -| FÅ | `/v1beta/models` | Tvillingene | -| INNLEGG | `/v1beta/models/{...path}` | Gemini generer innhold | -| INNLEGG | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Dedikerte leverandørruter +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Leverandørprefikset blir automatisk lagt til hvis det mangler. Umatchede modeller returnerer `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Semantisk buffer +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Eksempel på svar: +Response example: ```json { @@ -162,154 +162,164 @@ Eksempel på svar: --- -## Dashboard og administrasjon +## Dashboard & Management -### Autentisering +### Authentication -| Endepunkt | Metode | Beskrivelse | -| ----------------------------- | -------- | ---------------------- | -| `/api/auth/login` | INNLEGG | Logg inn | -| `/api/auth/logout` | INNLEGG | Logg ut | -| `/api/settings/require-login` | GET/SETT | Bytt innlogging kreves | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Leverandøradministrasjon +### Provider Management -| Endepunkt | Metode | Beskrivelse | -| ---------------------------- | -------------- | ------------------------------- | -| `/api/providers` | GET/POST | Liste / opprette leverandører | -| `/api/providers/[id]` | GET/SETT/SLETT | Administrer en leverandør | -| `/api/providers/[id]/test` | INNLEGG | Test leverandørtilkobling | -| `/api/providers/[id]/models` | FÅ | Liste leverandørmodeller | -| `/api/providers/validate` | INNLEGG | Valider leverandørkonfigurasjon | -| `/api/provider-nodes*` | Diverse | Leverandørnodeadministrasjon | -| `/api/provider-models` | GET/POST/SLETT | Egendefinerte modeller | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth-flyter +### OAuth Flows -| Endepunkt | Metode | Beskrivelse | -| -------------------------------- | ------- | ------------------------- | -| `/api/oauth/[provider]/[action]` | Diverse | Leverandørspesifikk OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Ruting og konfig +### Routing & Config -| Endepunkt | Metode | Beskrivelse | -| --------------------- | -------- | ------------------------------------- | -| `/api/models/alias` | GET/POST | Modellaliaser | -| `/api/models/catalog` | FÅ | Alle modeller etter leverandør + type | -| `/api/combos*` | Diverse | Combo management | -| `/api/keys*` | Diverse | API-nøkkelstyring | -| `/api/pricing` | FÅ | Modellprising | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Bruk og analyse +### Usage & Analytics -| Endepunkt | Metode | Beskrivelse | -| --------------------------- | ------ | -------------------------- | -| `/api/usage/history` | FÅ | Brukshistorikk | -| `/api/usage/logs` | FÅ | Brukslogger | -| `/api/usage/request-logs` | FÅ | Logger på forespørselsnivå | -| `/api/usage/[connectionId]` | FÅ | Bruk per tilkobling | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Innstillinger +### Settings -| Endepunkt | Metode | Beskrivelse | -| ------------------------------- | -------- | ------------------------------------- | -| `/api/settings` | GET/SETT | Generelle innstillinger | -| `/api/settings/proxy` | GET/SETT | Nettverks proxy-konfigurasjon | -| `/api/settings/proxy/test` | INNLEGG | Test proxy-tilkobling | -| `/api/settings/ip-filter` | GET/SETT | IP-godkjenningsliste/blokkeringsliste | -| `/api/settings/thinking-budget` | GET/SETT | Begrunnelse token budsjett | -| `/api/settings/system-prompt` | GET/SETT | Global systemmelding | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Overvåking +### Monitoring -| Endepunkt | Metode | Beskrivelse | -| ------------------------ | -------- | ------------------------ | -| `/api/sessions` | FÅ | Aktiv øktsporing | -| `/api/rate-limits` | FÅ | Satsgrenser per konto | -| `/api/monitoring/health` | FÅ | Helsesjekk | -| `/api/cache` | FÅ/SLETT | Bufferstatistikk / slett | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Sikkerhetskopiering og eksport/import +### Backup & Export/Import -| Endepunkt | Metode | Beskrivelse | -| --------------------------- | ------- | ---------------------------------------------- | -| `/api/db-backups` | FÅ | Liste tilgjengelige sikkerhetskopier | -| `/api/db-backups` | PUT | Lag en manuell sikkerhetskopi | -| `/api/db-backups` | INNLEGG | Gjenopprett fra en bestemt sikkerhetskopi | -| `/api/db-backups/export` | FÅ | Last ned database som .sqlite-fil | -| `/api/db-backups/import` | INNLEGG | Last opp .sqlite-fil for å erstatte databasen | -| `/api/db-backups/exportAll` | FÅ | Last ned full sikkerhetskopi som .tar.gz-arkiv | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | ### Cloud Sync -| Endepunkt | Metode | Beskrivelse | -| ---------------------- | ------- | ----------------------------- | -| `/api/sync/cloud` | Diverse | Skysynkroniseringsoperasjoner | -| `/api/sync/initialize` | INNLEGG | Initialiser synkronisering | -| `/api/cloud/*` | Diverse | Cloud management | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI-verktøy +### CLI Tools -| Endepunkt | Metode | Beskrivelse | -| ---------------------------------- | ------ | --------------------- | -| `/api/cli-tools/claude-settings` | FÅ | Claude CLI status | -| `/api/cli-tools/codex-settings` | FÅ | Codex CLI-status | -| `/api/cli-tools/droid-settings` | FÅ | Droid CLI-status | -| `/api/cli-tools/openclaw-settings` | FÅ | OpenClaw CLI-status | -| `/api/cli-tools/runtime/[toolId]` | FÅ | Generisk CLI kjøretid | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -CLI-svar inkluderer: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Resiliens- og rategrenser +### ACP Agents -| Endepunkt | Metode | Beskrivelse | -| ----------------------- | -------- | ------------------------------ | -| `/api/resilience` | GET/SETT | Få/oppdater resiliensprofiler | -| `/api/resilience/reset` | INNLEGG | Tilbakestill effektbrytere | -| `/api/rate-limits` | FÅ | Satsgrensestatus per konto | -| `/api/rate-limit` | FÅ | Global rategrensekonfigurasjon | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Evaler +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Endepunkt | Metode | Beskrivelse | -| ------------ | -------- | ---------------------------------- | -| `/api/evals` | GET/POST | List eval suiter / kjør evaluering | +### Resilience & Rate Limits -### Retningslinjer +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Endepunkt | Metode | Beskrivelse | -| --------------- | -------------- | -------------------------- | -| `/api/policies` | GET/POST/SLETT | Administrer rutingpolicyer | +### Evals -### Samsvar +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Endepunkt | Metode | Beskrivelse | -| --------------------------- | ------ | ------------------------------------ | -| `/api/compliance/audit-log` | FÅ | Overholdelsesrevisjonslogg (siste N) | +### Policies -### v1beta (Gemini-kompatibel) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Endepunkt | Metode | Beskrivelse | -| -------------------------- | ------- | ---------------------------------- | -| `/v1beta/models` | FÅ | Vis modeller i Gemini-format | -| `/v1beta/models/{...path}` | INNLEGG | Gemini `generateContent` endepunkt | +### Compliance -Disse endepunktene gjenspeiler Geminis API-format for klienter som forventer naturlig Gemini SDK-kompatibilitet. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### Interne / System APIer +### v1beta (Gemini-Compatible) -| Endepunkt | Metode | Beskrivelse | -| --------------- | ------- | ----------------------------------------------------------------- | -| `/api/init` | FÅ | Initialiseringssjekk av applikasjonen (brukes ved første kjøring) | -| `/api/tags` | FÅ | Ollama-kompatible modellkoder (for Ollama-klienter) | -| `/api/restart` | INNLEGG | Utløs grasiøs serveromstart | -| `/api/shutdown` | INNLEGG | Utløs grasiøs serveravslutning | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Merk:** Disse endepunktene brukes internt av systemet eller for Ollama-klientkompatibilitet. De kalles vanligvis ikke opp av sluttbrukere. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Lydtranskripsjon +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transkribere lydfiler ved hjelp av Deepgram eller AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Forespørsel:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Svar:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Støttede leverandører:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Støttede formater:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Ollama-kompatibilitet +## Ollama Compatibility -For klienter som bruker Ollamas API-format: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Forespørsler oversettes automatisk mellom Ollama og interne formater. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetri +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Svar:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Budsjett +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Modelltilgjengelighet +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Forespørselsbehandling +## Request Processing -1. Klient sender forespørsel til `/v1/*` -2. Rutebehandler anroper `handleChat`, `handleEmbedding`, `handleAudioTranscription` eller `handleImageGeneration` -3. Modellen er løst (direkte leverandør/modell eller alias/kombinasjon) -4. Påloggingsinformasjon valgt fra lokal DB med filtrering av kontotilgjengelighet -5. For chat: `handleChatCore` — formatdeteksjon, oversettelse, hurtigbuffersjekk, idempotenssjekk -6. Leverandør eksekutør sender oppstrømsforespørsel -7. Svar oversatt tilbake til klientformat (chat) eller returnert som det er (innbygginger/bilder/lyd) -8. Bruk/logging registrert -9. Fallback gjelder feil i henhold til kombinasjonsregler +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Full arkitekturreferanse: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Autentisering +## Authentication -- Dashboard-ruter (`/dashboard/*`) bruker `auth_token`-informasjonskapsel -- Innlogging bruker lagret passordhash; fallback til `INITIAL_PASSWORD` -- `requireLogin` kan byttes via `/api/settings/require-login` -- `/v1/*`-ruter krever valgfritt Bearer API-nøkkel når `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/no/ARCHITECTURE.md b/docs/i18n/no/ARCHITECTURE.md index d443e487bc..258d62df53 100644 --- a/docs/i18n/no/ARCHITECTURE.md +++ b/docs/i18n/no/ARCHITECTURE.md @@ -1,72 +1,71 @@ -# OmniRoute-arkitektur +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Sist oppdatert: 2026-02-18_ +_Last updated: 2026-03-04_ -## Sammendrag +## Executive Summary -OmniRoute er en lokal AI-rutinggateway og dashbord bygget på Next.js. -Den gir et enkelt OpenAI-kompatibelt endepunkt (`/v1/*`) og ruter trafikk på tvers av flere oppstrømsleverandører med oversettelse, reserve, token-oppdatering og brukssporing. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Kjernefunksjoner: +Core capabilities: -- OpenAI-kompatibel API-overflate for CLI/verktøy (28 leverandører) -- Forespørsel/svar oversettelse på tvers av leverandørformater -- Modellkombinasjonsfallback (multimodellsekvens) -- Reserveback på kontonivå (multikonto per leverandør) -- OAuth + API-nøkkelleverandør tilkoblingsadministrasjon -- Innbyggingsgenerering via `/v1/embeddings` (6 leverandører, 9 modeller) -- Bildegenerering via `/v1/images/generations` (4 leverandører, 9 modeller) -- Tenk tag-parsing (`...`) for resonneringsmodeller -- Respons sanitization for streng OpenAI SDK-kompatibilitet -- Rollenormalisering (utvikler→system, system→bruker) for kompatibilitet på tvers av leverandører -- Konvertering av strukturert utdata (json_schema → Gemini responseSchema) -- Lokal utholdenhet for leverandører, nøkler, aliaser, kombinasjoner, innstillinger, priser -- Bruks-/kostnadssporing og forespørselslogging -- Valgfri skysynkronisering for synkronisering av flere enheter/tilstander -- IP-godkjenningsliste/blokkeringsliste for API-tilgangskontroll -- Tenker budsjettstyring (gjennomgang/auto/tilpasset/tilpasset) -- Injeksjon av et globalt system -- Sesjonssporing og fingeravtrykk -- Forbedret prisbegrensning per konto med leverandørspesifikke profiler -- Strømbrytermønster for leverandørens motstandskraft -- Anti-tordenbeskyttelse med mutex-låsing -- Signaturbasert forespørselsdedupliseringsbuffer -- Domenelag: modelltilgjengelighet, kostnadsregler, reservepolicy, lockoutpolicy -- Vedvarende domenetilstand (SQLite-gjennomskrivingsbuffer for reserver, budsjetter, lockouts, strømbrytere) -- Policymotor for sentralisert forespørselsevaluering (lockout → budsjett → reserve) -- Be om telemetri med p50/p95/p99 latensaggregering -- Korrelasjons-ID (X-Request-Id) for ende-til-ende-sporing -- Overholdelsesrevisjonslogging med opt-out per API-nøkkel -- Eval rammeverk for LLM kvalitetssikring -- Resilience UI-dashbord med sanntids strømbryterstatus -- Modulære OAuth-leverandører (12 individuelle moduler under `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Primær kjøretidsmodell: +Primary runtime model: -– Next.js app-ruter under `src/app/api/*` implementerer både dashbord-APIer og kompatibilitets-APIer +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -- En delt SSE/rutingkjerne i `src/sse/*` + `open-sse/*` håndterer leverandørutførelse, oversettelse, strømming, fallback og bruk +## Scope and Boundaries -## Omfang og grenser +### In Scope -### I omfang +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -- Lokal gateway kjøretid -- Dashboard management APIer -- Leverandørautentisering og tokenoppdatering -- Be om oversettelse og SSE-streaming -- Lokal stat + bruksutholdenhet -- Valgfri skysynkroniseringsorkestrering +### Out of Scope -### Utenfor omfang +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -- Implementering av skytjenester bak `NEXT_PUBLIC_CLOUD_URL` -- Leverandør SLA/kontrollplan utenfor lokal prosess -- Eksterne CLI-binærfiler i seg selv (Claude CLI, Codex CLI, etc.) - -## Systemkontekst på høyt nivå +## High-Level System Context ```mermaid flowchart LR @@ -82,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -114,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Kjernekjøringskomponenter +## Core Runtime Components -## 1) API og rutinglag (Next.js App Routes) +## 1) API and Routing Layer (Next.js App Routes) -Hovedkataloger: +Main directories: -- `src/app/api/v1/*` og `src/app/api/v1beta/*` for kompatibilitets-APIer -- `src/app/api/*` for administrasjons-/konfigurasjons-APIer -- Neste omskrivninger i `next.config.mjs` kart `/v1/*` til `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Viktige kompatibilitetsruter: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — inkluderer tilpassede modeller med `custom: true` -- `src/app/api/v1/embeddings/route.ts` — innebyggingsgenerering (6 leverandører) -- `src/app/api/v1/images/generations/route.ts` — bildegenerering (4+ leverandører inkl. Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedikert chat per leverandør -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedikerte innbygginger per leverandør -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedikerte bilder per leverandør +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Administrasjonsdomener: +Management domains: -- Auth/innstillinger: `src/app/api/auth/*`, `src/app/api/settings/*` -- Leverandører/tilkoblinger: `src/app/api/providers*` -- Leverandørnoder: `src/app/api/provider-nodes*` -- Egendefinerte modeller: `src/app/api/provider-models` (GET/POST/DELETE) -- Modellkatalog: `src/app/api/models/catalog` (GET) -- Proxy-konfigurasjon: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Nøkler/aliaser/kombinasjoner/priser: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Bruk: `src/app/api/usage/*` -- Synkronisering/sky: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI-verktøyhjelpere: `src/app/api/cli-tools/*` -- IP-filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Tenkebudsjett: `src/app/api/settings/thinking-budget` (GET/PUT) -- Systemmelding: `src/app/api/settings/system-prompt` (GET/PUT) -- Økter: `src/app/api/sessions` (GET) -- Satsgrenser: `src/app/api/rate-limits` (GET) -- Motstandsdyktighet: `src/app/api/resilience` (GET/PATCH) — leverandørprofiler, strømbryter, rategrensetilstand -- Resiliens tilbakestilling: `src/app/api/resilience/reset` (POST) — tilbakestill brytere + nedkjøling -- Bufferstatistikk: `src/app/api/cache/stats` (GET/DELETE) -- Modelltilgjengelighet: `src/app/api/models/availability` (GET/POST) -- Telemetri: `src/app/api/telemetry/summary` (GET) - – Budsjett: `src/app/api/usage/budget` (GET/POST) -- Reservekjeder: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Overholdelsesrevisjon: `src/app/api/compliance/audit-log` (GET) -- Evaler: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Retningslinjer: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) ## 2) SSE + Translation Core -Hovedstrømningsmoduler: +Main flow modules: -- Inngang: `src/sse/handlers/chat.ts` -- Kjerneorkestrering: `open-sse/handlers/chatCore.ts` -- Leverandørutførelsesadaptere: `open-sse/executors/*` -- Formatdeteksjon/leverandørkonfigurasjon: `open-sse/services/provider.ts` -- Modellanalyse/oppløsning: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Kontoreservelogikk: `open-sse/services/accountFallback.ts` -- Oversettelsesregister: `open-sse/translator/index.ts` -- Strømtransformasjoner: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Bruksutvinning/normalisering: `open-sse/utils/usageTracking.ts` -- Think tag-parser: `open-sse/utils/thinkTagParser.ts` -- Innebyggingsbehandler: `open-sse/handlers/embeddings.ts` -- Innebyggingsleverandørregister: `open-sse/config/embeddingRegistry.ts` -- Bildegenereringsbehandler: `open-sse/handlers/imageGeneration.ts` -- Bildeleverandørs register: `open-sse/config/imageRegistry.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` - Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Rollenormalisering: `open-sse/services/roleNormalizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Tjenester (forretningslogikk): +Services (business logic): -- Kontovalg/score: `open-sse/services/accountSelector.ts` -- Kontekstlivssyklusadministrasjon: `open-sse/services/contextManager.ts` -- IP-filterhåndhevelse: `open-sse/services/ipFilter.ts` -- Øktsporing: `open-sse/services/sessionManager.ts` -- Be om deduplisering: `open-sse/services/signatureCache.ts` -- Systemprompt-injeksjon: `open-sse/services/systemPrompt.ts` -- Tenkende budsjettstyring: `open-sse/services/thinkingBudget.ts` -- Jokertegn modellruting: `open-sse/services/wildcardRouter.ts` -- Satsgrenseadministrasjon: `open-sse/services/rateLimitManager.ts` -- Strømbryter: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Domenelagsmoduler: +Domain layer modules: -- Modelltilgjengelighet: `src/lib/domain/modelAvailability.ts` -- Kostnadsregler/budsjetter: `src/lib/domain/costRules.ts` - – Reservepolicy: `src/lib/domain/fallbackPolicy.ts` -- Kombinasjonsløser: `src/lib/domain/comboResolver.ts` - – Utelukkingspolicy: `src/lib/domain/lockoutPolicy.ts` -- Policymotor: `src/domain/policyEngine.ts` — sentralisert lockout → budsjett → reserveevaluering -- Feilkodekatalog: `src/lib/domain/errorCodes.ts` -- Forespørsels-ID: `src/lib/domain/requestId.ts` -- Tidsavbrudd for henting: `src/lib/domain/fetchTimeout.ts` -- Be om telemetri: `src/lib/domain/requestTelemetry.ts` -- Samsvar/revisjon: `src/lib/domain/compliance/index.ts` -- Evalløper: `src/lib/domain/evalRunner.ts` -- Vedvarende domenetilstand: `src/lib/db/domainState.ts` — SQLite CRUD for reservekjeder, budsjetter, kostnadshistorikk, lockouttilstand, strømbrytere +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth-leverandørmoduler (12 individuelle filer under `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Registerindeks: `src/lib/oauth/providers/index.ts` - – Individuelle leverandører: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Tynn innpakning: `src/lib/oauth/providers.ts` — re-eksport fra individuelle moduler +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Utholdenhetslag +## 3) Persistence Layer -Primær tilstand DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- fil: `${DATA_DIR}/db.json` (eller `$XDG_CONFIG_HOME/omniroute/db.json` når angitt, ellers `~/.omniroute/db.json`) -- enheter: providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Bruk DB: +Usage persistence: -- `src/lib/usageDb.ts` -- filer: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- følger samme grunnleggende katalogpolicy som `localDb` (`DATA_DIR`, deretter `XDG_CONFIG_HOME/omniroute` når angitt) -- dekomponert i fokuserte undermoduler: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -Domenetilstand DB (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — CRUD-operasjoner for domenetilstand -- Tabeller (opprettet i `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Gjennomskrivingsbuffermønster: kart i minnet er autoritative under kjøring; mutasjoner skrives synkront til SQLite; tilstand gjenopprettes fra DB ved kaldstart +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start ## 4) Auth + Security Surfaces -- Dashboard-informasjonskapselautentisering: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Generering/verifisering av API-nøkler: `src/shared/utils/apiKey.ts` -- Leverandørhemmeligheter vedvarte i `providerConnections`-oppføringer -- Utgående proxy-støtte via `open-sse/utils/proxyFetch.ts` (env vars) og `open-sse/utils/networkProxy.ts` (konfigurerbar per leverandør eller global) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) ## 5) Cloud Sync -- Planlegger init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Periodisk oppgave: `src/shared/services/cloudSyncScheduler.ts` -- Kontrollrute: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Forespørselslivssyklus (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -305,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Account Reserve Flow +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -335,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Reservebeslutninger er drevet av `open-sse/services/accountFallback.ts` ved hjelp av statuskoder og feilmeldingsheuristikk. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth Onboarding og Token Refresh Lifecycle +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -367,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Oppdatering under levende trafikk utføres inne i `open-sse/handlers/chatCore.ts` via eksekveren `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Cloud Sync Lifecycle (Aktiver / Synkroniser / Deaktiver) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -401,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Periodisk synkronisering utløses av `CloudSyncScheduler` når skyen er aktivert. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Datamodell og lagringskart +## Data Model and Storage Map ```mermaid erDiagram @@ -504,14 +504,14 @@ erDiagram } ``` -Fysiske lagringsfiler: +Physical storage files: -- hovedtilstand: `${DATA_DIR}/db.json` (eller `$XDG_CONFIG_HOME/omniroute/db.json` når angitt, ellers `~/.omniroute/db.json`) -- bruksstatistikk: `${DATA_DIR}/usage.json` -- be om logglinjer: `${DATA_DIR}/log.txt` -- valgfrie oversetter/forespørsler om feilsøkingsøkter: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Utrullingstopologi +## Deployment Topology ```mermaid flowchart LR @@ -523,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -542,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Modulmapping (beslutningskritisk) +## Module Mapping (Decision-Critical) -### Rute- og API-moduler +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: kompatibilitets-APIer -- `src/app/api/v1/providers/[provider]/*`: dedikerte ruter per leverandør (chat, innebygging, bilder) -- `src/app/api/providers*`: leverandør CRUD, validering, testing -- `src/app/api/provider-nodes*`: tilpasset kompatibel nodeadministrasjon -- `src/app/api/provider-models`: tilpasset modelladministrasjon (CRUD) -- `src/app/api/models/catalog`: full modellkatalog API (alle typer gruppert etter leverandør) -- `src/app/api/oauth/*`: OAuth/enhetskode flyter -- `src/app/api/keys*`: lokal API-nøkkellivssyklus -- `src/app/api/models/alias`: aliasadministrasjon -- `src/app/api/combos*`: reservekombinasjonsadministrasjon -- `src/app/api/pricing`: prisoverstyringer for kostnadsberegning -- `src/app/api/settings/proxy`: proxy-konfigurasjon (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: utgående proxy-tilkoblingstest (POST) -- `src/app/api/usage/*`: APIer for bruk og logger -- `src/app/api/sync/*` + `src/app/api/cloud/*`: skysynkronisering og skyvendte hjelpere -- `src/app/api/cli-tools/*`: lokale CLI-konfigurasjonsforfattere/kontrollere -- `src/app/api/settings/ip-filter`: IP-godkjenningsliste/blokkeringsliste (GET/PUT) -- `src/app/api/settings/thinking-budget`: budsjettkonfigurasjon for tenketoken (GET/PUT) -- `src/app/api/settings/system-prompt`: global systemmelding (GET/PUT) -- `src/app/api/sessions`: aktiv øktoppføring (GET) -- `src/app/api/rate-limits`: satsgrensestatus per konto (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Kjerne for ruting og utførelse +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: forespørsel om parse, kombinasjonshåndtering, kontovalgsløyfe -- `open-sse/handlers/chatCore.ts`: oversettelse, eksekutorutsendelse, prøv på nytt/oppdateringshåndtering, strømoppsett -- `open-sse/executors/*`: leverandørspesifikk nettverks- og formatatferd +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Oversettelsesregister og formatkonverterere +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: oversetterregister og orkestrering -- Be om oversettere: `open-sse/translator/request/*` -- Svaroversettere: `open-sse/translator/response/*` -- Formatkonstanter: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Utholdenhet +### Persistence -- `src/lib/localDb.ts`: vedvarende konfig/tilstand -- `src/lib/usageDb.ts`: brukshistorikk og rullende forespørselslogger +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Leverandørdekning (strategimønster) +## Provider Executor Coverage (Strategy Pattern) -Hver leverandør har en spesialisert eksekutør som utvider `BaseExecutor` (i `open-sse/executors/base.ts`), som gir URL-bygging, headerkonstruksjon, forsøk på nytt med eksponentiell backoff, legitimasjonsoppdateringskroker og `execute()` orkestreringsmetoden. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Utfører | Leverandør(er) | Spesiell håndtering | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamisk URL/header-konfigurasjon per leverandør | -| `AntigravityExecutor` | Google Antigravity | Egendefinerte prosjekt-/sesjons-ID-er, Prøv på nytt etter parsing | -| `CodexExecutor` | OpenAI Codex | Injiserer systeminstruksjoner, tvinger resonnementinnsats | -| `CursorExecutor` | Markør IDE | ConnectRPC-protokoll, Protobuf-koding, forespørsel om signering via sjekksum | -| `GithubExecutor` | GitHub Copilot | Copilot token oppdatering, VSCode-lignende overskrifter | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binært format → SSE-konvertering | -| `GeminiCLIExecutor` | Gemini CLI | Oppdateringssyklus for Google OAuth-token | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Alle andre leverandører (inkludert tilpassede kompatible noder) bruker `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Leverandørkompatibilitetsmatrise +## Provider Compatibility Matrix -| Leverandør | Format | Auth | Stream | Ikke-stream | Token oppdatering | Bruks-API | -| ---------------- | --------------- | --------------------- | ---------------- | ----------- | ----------------- | ------------------------ | -| Claude | claude | API-nøkkel / OAuth | ✅ | ✅ | ✅ | ⚠️ Kun administrator | -| Tvillingene | Gemini | API-nøkkel / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Antigravitasjon | antigravitasjon | OAuth | ✅ | ✅ | ✅ | ✅ Full kvote API | -| OpenAI | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-svar | OAuth | ✅ tvunget | ❌ | ✅ | ✅ Satsgrenser | -| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Kvote øyeblikksbilder | -| Markør | markør | Egendefinert sjekksum | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Bruksgrenser | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per forespørsel | -| iFlow | openai | OAuth (Grunnleggende) | ✅ | ✅ | ✅ | ⚠️ Per forespørsel | -| OpenRouter | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| Forvirring | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| Sammen AI | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| Fyrverkeri AI | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| Cerebras | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| Sammenheng | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API-nøkkel | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Formatoversettelsesdekning +## Format Translation Coverage -Oppdagede kildeformater inkluderer: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Målformater inkluderer: +Target formats include: -- OpenAI chat/svar +- OpenAI chat/Responses - Claude -- Gemini/Gemini-CLI/Antigravity konvolutt +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Markør +- Cursor -Oversettelser bruker **OpenAI som hub-format** – alle konverteringer går gjennom OpenAI som mellomliggende: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Oversettelser velges dynamisk basert på kildens nyttelastform og leverandørens målformat. +Translations are selected dynamically based on source payload shape and provider target format. -Ytterligere behandlingslag i oversettelsespipelinen: +Additional processing layers in the translation pipeline: -- **Responssanering** - Fjerner ikke-standardiserte felt fra OpenAI-formatsvar (både streaming og ikke-streaming) for å sikre streng SDK-overholdelse -- **Rollenormalisering** — Konverterer `developer` → `system` for ikke-OpenAI-mål; slår sammen `system` → `user` for modeller som avviser systemrollen (GLM, ERNIE) -- **Tenk tag-utvinning** — analyserer `...` blokker fra innhold til feltet `reasoning_content` -- **Structured output** — Konverterer OpenAI `response_format.json_schema` til Gemini's `responseMimeType` + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Støttede API-endepunkter +## Supported API Endpoints -| Endepunkt | Format | Handler | -| -------------------------------------------------- | ---------------------- | ----------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Meldinger | Samme behandler (automatisk oppdaget) | -| `POST /v1/responses` | OpenAI-svar | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Modellliste | API-rute | -| `POST /v1/images/generations` | OpenAI-bilder | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Modellliste | API-rute | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedikert per leverandør med modellvalidering | -| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedikert per leverandør med modellvalidering | -| `POST /v1/providers/{provider}/images/generations` | OpenAI-bilder | Dedikert per leverandør med modellvalidering | -| `POST /v1/messages/count_tokens` | Claude Token Count | API-rute | -| `GET /v1/models` | OpenAI-modellliste | API-rute (chat + innebygging + bilde + tilpassede modeller) | -| `GET /api/models/catalog` | Katalog | Alle modeller gruppert etter leverandør + type | -| `POST /v1beta/models/*:streamGenerateContent` | Gemini innfødt | API-rute | -| `GET/PUT/DELETE /api/settings/proxy` | Proxy-konfigurasjon | Nettverks proxy-konfigurasjon | -| `POST /api/settings/proxy/test` | Proxy-tilkobling | Proxy-helse/tilkoblingstestendepunkt | -| `GET/POST/DELETE /api/provider-models` | Egendefinerte modeller | Tilpasset modelladministrasjon per leverandør | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | ## Bypass Handler -Bypass-behandleren (`open-sse/utils/bypassHandler.ts`) avskjærer kjente "kasting"-forespørsler fra Claude CLI – oppvarmingspinger, tittelutdrag og tokentellinger – og returnerer et **falsk svar** uten å forbruke oppstrømsleverandørtokens. Dette utløses bare når `User-Agent` inneholder `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Be om Logger Pipeline +## Request Logger Pipeline -Forespørselsloggeren (`open-sse/utils/requestLogger.ts`) gir en 7-trinns feilsøkingsloggingspipeline, deaktivert som standard, aktivert via `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Filer skrives til `/logs//` for hver forespørselsøkt. +Files are written to `/logs//` for each request session. -## Feilmoduser og motstandskraft +## Failure Modes and Resilience -## 1) Konto/leverandørtilgjengelighet +## 1) Account/Provider Availability -- Nedkjøling av leverandørens konto på forbigående/rate/auth-feil -- kontoreserve før mislykket forespørsel -- combo modell fallback når gjeldende modell/leverandørbane er oppbrukt +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Token-utløp +## 2) Token Expiry -- forhåndssjekk og oppdater med nytt forsøk for leverandører som kan oppdateres -- 401/403 prøv på nytt etter oppdateringsforsøk i kjernebanen +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Strømsikkerhet +## 3) Stream Safety -- frakoblingsbevisst strømkontroller -- oversettelsesstrøm med end-of-stream flush og `[DONE]` håndtering - – fallback for bruksestimat når leverandørbruksmetadata mangler +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Cloud Sync Degradering +## 4) Cloud Sync Degradation -- Synkroniseringsfeil dukker opp, men lokal kjøretid fortsetter -- planleggeren har logikk som kan forsøke på nytt, men periodisk kjøring kaller for øyeblikket enkeltforsøkssynkronisering som standard +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Dataintegritet +## 5) Data Integrity -- DB-formmigrering/reparasjon for manglende nøkler -- korrupte JSON-tilbakestillingstiltak for localDb og usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Observerbarhet og operasjonelle signaler +## Observability and Operational Signals -Synlighetskilder for kjøretid: +Runtime visibility sources: -- konsolllogger fra `src/sse/utils/logger.ts` -- bruksaggregater per forespørsel i `usage.json` -- logg på status for tekstforespørsel `log.txt` -- valgfrie dype forespørsels-/oversettelseslogger under `logs/` når `ENABLE_REQUEST_LOGS=true` -- endepunkter for dashbordbruk (`/api/usage/*`) for brukergrensesnittforbruk +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Sikkerhetssensitive grenser +## Security-Sensitive Boundaries -- JWT-hemmelighet (`JWT_SECRET`) sikrer bekreftelse/signering av informasjonskapsler for dashbordøkten -- Innledende passordreserve (`INITIAL_PASSWORD`, standard `123456`) må overstyres i reelle distribusjoner -- API-nøkkel HMAC-hemmelighet (`API_KEY_SECRET`) sikrer generert lokalt API-nøkkelformat -- Leverandørhemmeligheter (API-nøkler/-tokens) er bevart i lokal DB og bør beskyttes på filsystemnivå -- Sluttpunkter for skysynkronisering er avhengige av API-nøkkelautentisering + maskin-ID-semantikk +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Miljø- og kjøretidsmatrise +## Environment and Runtime Matrix -Miljøvariabler som brukes aktivt av kode: +Environment variables actively used by code: - App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` -- Lagring: `DATA_DIR` -- Kompatibel nodeoppførsel: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Valgfri lagringsbaseoverstyring (Linux/macOS når `DATA_DIR` ikke er innstilt): `XDG_CONFIG_HOME` -- Sikkerhetshashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` - Logging: `ENABLE_REQUEST_LOGS` -- Synkronisering/nettadresser i nettskyen: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Utgående proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` og varianter med små bokstaver -- SOCKS5-funksjonsflagg: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` - – Plattform-/kjøretidshjelpere (ikke appspesifikk konfigurasjon): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Kjente arkitektoniske notater +## Known Architectural Notes -1. `usageDb` og `localDb` deler nå samme grunnkatalogpolicy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) med eldre filmigrering. -2. `/api/v1/route.ts` returnerer en statisk modellliste og er ikke hovedmodellkilden som brukes av `/v1/models`. -3. Forespørselslogger skriver fullstendige overskrifter/tekst når den er aktivert; behandle loggkatalogen som sensitiv. -4. Skyadferd avhenger av korrekt `NEXT_PUBLIC_BASE_URL` og skyendepunkts tilgjengelighet. -5. `open-sse/`-katalogen er publisert som `@omniroute/open-sse` **npm-arbeidsområdepakken**. Kildekoden importerer den via `@omniroute/open-sse/...` (løst av Next.js `transpilePackages`). Filbaner i dette dokumentet bruker fortsatt katalognavnet `open-sse/` for konsistens. -6. Diagrammer i dashbordet bruker **Recharts** (SVG-basert) for tilgjengelige, interaktive analysevisualiseringer (stolpediagram for modellbruk, leverandøroversiktstabeller med suksessrater). -7. E2E-tester bruker **Playwright** (`tests/e2e/`), kjøres via `npm run test:e2e`. Enhetstester bruker **Node.js testløper** (`tests/unit/`), kjøres via `npm run test:plan3`. Kildekoden under `src/` er **TypeScript** (`.ts`/`.tsx`); arbeidsområdet `open-sse/` forblir JavaScript (`.js`). -8. Innstillinger-siden er organisert i 5 faner: Sikkerhet, Ruting (6 globale strategier: fill-first, round-robin, p2c, random, minst brukt, kostnadsoptimalisert), Resiliens (redigerbare hastighetsgrenser, strømbryter, policyer), AI (tenkebudsjett, systemprompt, promptbuffer), Advanced (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Kontrolliste for operasjonell verifisering +## Operational Verification Checklist -- Bygg fra kilde: `npm run build` -- Bygg Docker-bilde: `docker build -t omniroute .` -- Start tjenesten og bekreft: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- CLI-målgrunnadressen skal være `http://:20128/v1` når `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/no/CODEBASE_DOCUMENTATION.md b/docs/i18n/no/CODEBASE_DOCUMENTATION.md index e41bbd6f98..303880c198 100644 --- a/docs/i18n/no/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/no/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Kodebasedokumentasjon +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> En omfattende, nybegynnervennlig guide til **omniroute** multi-leverandør AI proxy-ruter. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Hva er omniroute? +## 1. What Is omniroute? -omniroute er en **proxy-ruter** som sitter mellom AI-klienter (Claude CLI, Codex, Cursor IDE, etc.) og AI-leverandører (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Det løser ett stort problem: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Ulike AI-klienter snakker forskjellige "språk" (API-formater), og forskjellige AI-leverandører forventer også forskjellige "språk".** omniroute oversetter mellom dem automatisk. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Tenk på det som en universell oversetter i FN - enhver delegat kan snakke hvilket som helst språk, og oversetteren konverterer det til en hvilken som helst annen delegat. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Arkitekturoversikt +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Kjerneprinsipp: Hub-and-Speake-oversettelse +### Core Principle: Hub-and-Spoke Translation -All formatoversettelse går gjennom **OpenAI-formatet som navet**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Dette betyr at du bare trenger **N oversettere** (én per format) i stedet for **N²** (hvert par). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Prosjektstruktur +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Modul-for-modul-oversikt +## 4. Module-by-Module Breakdown ### 4.1 Config (`open-sse/config/`) -**enkelt kilde til sannhet** for alle leverandørkonfigurasjoner. +The **single source of truth** for all provider configuration. -| Fil | Formål | -| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` objekt med grunnleggende URL-er, OAuth-legitimasjon (standard), overskrifter og standard systemmeldinger for hver leverandør. Definerer også `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` og `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Laster inn ekstern legitimasjon fra `data/provider-credentials.json` og slår dem sammen over de hardkodede standardinnstillingene i `PROVIDERS`. Holder hemmeligheter utenfor kildekontroll samtidig som bakoverkompatibiliteten opprettholdes. | -| `providerModels.ts` | Sentralt modellregister: kartleverandøraliaser → modell-ID-er. Funksjoner som `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Systeminstruksjoner injisert i Codex-forespørsler (redigeringsbegrensninger, sandkasseregler, godkjenningspolicyer). | -| `defaultThinkingSignature.ts` | Standard "tenkende" signaturer for Claude og Gemini-modeller. | -| `ollamaModels.ts` | Skjemadefinisjon for lokale Ollama-modeller (navn, størrelse, familie, kvantisering). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Innlastingsflyt for legitimasjon +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Eksekutører (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Eksekutører kapsler inn **leverandørspesifikk logikk** ved å bruke **strategimønsteret**. Hver eksekutør overstyrer basismetoder etter behov. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Utfører | Leverandør | Nøkkelspesialiseringer | -| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Abstrakt base: URL-bygging, overskrifter, logikk på nytt, oppdatering av legitimasjon | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generisk OAuth-tokenoppdatering for standardleverandører | -| `antigravity.ts` | Google Cloud Code | Prosjekt-/sesjons-ID generering, multi-URL fallback, tilpasset gjenforsøk på parsing fra feilmeldinger ("tilbakestill etter 2t7m23s") | -| `cursor.ts` | Markør IDE | **Mest kompliserte**: SHA-256 kontrollsum-authorisont, Protobuf-forespørselskoding, binær EventStream → SSE-svarparsing | -| `codex.ts` | OpenAI Codex | Injiserer systeminstruksjoner, administrerer tenkenivåer, fjerner ustøttede parametere | -| `gemini-cli.ts` | Google Gemini CLI | Egendefinert URL-bygging (`streamGenerateContent`), Google OAuth-tokenoppdatering | -| `github.ts` | GitHub Copilot | Dobbelt token-system (GitHub OAuth + Copilot-token), VSCode-header-etterligning | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binær parsing, AMZN hendelsesrammer, token estimering | -| `index.ts` | — | Fabrikk: navn på kartleverandør → eksekveringsklasse, med standard reserve | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Behandlere (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**Orkestreringslaget** — koordinerer oversettelse, utførelse, strømming og feilhåndtering. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Fil | Formål | +| File | Purpose | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Sentralorkester** (~600 linjer). Håndterer hele forespørselens livssyklus: formatdeteksjon → oversettelse → eksekveringssending → streaming/ikke-streaming-svar → token-oppdatering → feilhåndtering → brukslogging. | -| `responsesHandler.ts` | Adapter for OpenAIs Responses API: konverterer svarformat → Chatfullføringer → sender til `chatCore` → konverterer SSE tilbake til svarformat. | -| `embeddings.ts` | Innebyggingsgenereringshåndterer: løser innbyggingsmodell → leverandør, sender til leverandør-API, returnerer OpenAI-kompatibel innbyggingssvar. Støtter 6+ leverandører. | -| `imageGeneration.ts` | Bildegenereringshåndterer: løser bildemodell → leverandør, støtter OpenAI-kompatibel, Gemini-image (Antigravity) og fallback (Nebius) moduser. Returnerer base64- eller URL-bilder. | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Be om livssyklus (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Tjenester (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Forretningslogikk som støtter behandlerne og utførerne. +Business logic that supports the handlers and executors. -| Fil | Formål | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `provider.ts` | **Formatgjenkjenning** (`detectFormat`): analyser forespørsler om kroppsstruktur for å identifisere Claude/OpenAI/Gemini/Antigravity/Responses-formater (inkluderer `max_tokens` heuristikk for Claude). Også: URL-bygging, header-bygging, normalisering av tenkekonfigurasjon. Støtter `openai-compatible-*` og `anthropic-compatible-*` dynamiske leverandører. | -| `model.ts` | Parsing av modellstreng (`claude/model-name` → `{provider: "claude", model: "model-name"}`), aliasoppløsning med kollisjonsdeteksjon, inngangssanering (avviser banegjennomgang/kontrolltegn) og modellinformasjonsoppløsning med støtte for asynkron alias-getter. | -| `accountFallback.ts` | Hastighetsgrensehåndtering: eksponentiell backoff (1s → 2s → 4s → maks 2min), kontonedkjølingsadministrasjon, feilklassifisering (hvilke feil utløser fallback kontra ikke). | -| `tokenRefresh.ts` | OAuth-tokenoppdatering for **alle leverandører**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Inkluderer under flyging løftededupliseringsbuffer og forsøk på nytt med eksponentiell backoff. | -| `combo.ts` | **Kombomodeller**: kjeder av reservemodeller. Hvis modell A mislykkes med en fallback-kvalifisert feil, prøv modell B, deretter C osv. Returnerer faktiske oppstrømsstatuskoder. | -| `usage.ts` | Henter kvote-/bruksdata fra leverandør-API-er (GitHub Copilot-kvoter, Antigravity-modellkvoter, Codex-hastighetsgrenser, Kiro-brukssammenbrudd, Claude-innstillinger). | -| `accountSelector.ts` | Smart kontovalg med scoringsalgoritme: vurderer prioritet, helsestatus, round-robin-posisjon og nedkjølingstilstand for å velge den optimale kontoen for hver forespørsel. | -| `contextManager.ts` | Be om kontekstlivssyklusadministrasjon: oppretter og sporer kontekstobjekter per forespørsel med metadata (forespørsels-ID, tidsstempler, leverandørinformasjon) for feilsøking og logging. | -| `ipFilter.ts` | IP-basert tilgangskontroll: støtter tillatelsesliste- og blokkeringsmodus. Validerer klient-IP mot konfigurerte regler før API-forespørsler behandles. | -| `sessionManager.ts` | Sesjonssporing med klientfingeravtrykk: sporer aktive økter ved å bruke hashed klientidentifikatorer, overvåker antall forespørsler og gir øktberegninger. | -| `signatureCache.ts` | Forespørselssignaturbasert dedupliseringsbuffer: forhindrer dupliserte forespørsler ved å bufre nylige forespørselssignaturer og returnere bufrede svar for identiske forespørsler innen et tidsvindu. | -| `systemPrompt.ts` | Global systemmeldingsinjeksjon: legger til eller legger til en konfigurerbar systemmelding til alle forespørsler, med kompatibilitetshåndtering per leverandør. | -| `thinkingBudget.ts` | Reasoning token budsjettadministrasjon: støtter passthrough, auto (strip thinking config), tilpasset (fast budsjett) og adaptive (kompleksitetsskalert) moduser for å kontrollere tenkning/resonnering tokens. | -| `wildcardRouter.ts` | Ruting av jokertegnmodellmønster: løser jokertegnmønstre (f.eks. `*/claude-*`) til konkrete leverandør/modellpar basert på tilgjengelighet og prioritet. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Token Refresh Deduplisering +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Account Reserve State Machine +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Kombimodellkjede +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Oversetter (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**formatoversettelsesmotoren** bruker et selvregistrerende plugin-system. +The **format translation engine** using a self-registering plugin system. -#### Arkitektur +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Katalog | Filer | Beskrivelse | -| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 oversettere | Konverter forespørselstekster mellom formater. Hver fil registreres selv via `register(from, to, fn)` ved import. | -| `response/` | 7 oversettere | Konverter strømmeresponsbiter mellom formater. Håndterer SSE-hendelsestyper, tenkeblokker, verktøykall. | -| `helpers/` | 6 hjelpere | Delte verktøy: `claudeHelper` (uttrekking av systemprompt, tenkekonfigurasjon), `geminiHelper` (deler-/innholdskartlegging), `openaiHelper` (formatfiltrering), `toolCallHelper` (ID-generering, manglende responsinjeksjon), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Oversettelsesmotor: `translateRequest()`, `translateResponse()`, statlig ledelse, register. | -| `formats.ts` | — | Formatkonstanter: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Nøkkeldesign: Selvregistrerende plugins +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -397,15 +397,15 @@ import "./request/claude-to-openai.js"; // ← self-registers ### 4.6 Utils (`open-sse/utils/`) -| Fil | Formål | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Bygging av feilrespons (OpenAI-kompatibelt format), oppstrøms feilparsing, Antigravity-utvinning på nytt fra feilmeldinger, SSE-feilstrømming. | -| `stream.ts` | **SSE Transform Stream** — kjernestrømmingsrørledningen. To moduser: `TRANSLATE` (fullformatoversettelse) og `PASSTHROUGH` (normalisere + ekstraksjonsbruk). Håndterer chunk-buffring, bruksestimat, sporing av innholdslengde. Per-stream koder/dekoderforekomster unngår delt tilstand. | -| `streamHelpers.ts` | SSE-verktøy på lavt nivå: `parseSSELine` (tomromtolerant), `hasValuableContent` (filtrerer tomme deler for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (formatbevisst SSE-serialisering med `perf_metrics`-opprydding). | -| `usageTracking.ts` | Uttrekk av tokenbruk fra ethvert format (Claude/OpenAI/Gemini/Responses), estimering med separate verktøy/melding-char-per-token-forhold, buffertillegg (sikkerhetsmargin for 2000 tokens), formatspesifikk feltfiltrering, konsolllogging med ANSI-farger. | -| `requestLogger.ts` | Filbasert forespørselslogging (opt-in via `ENABLE_REQUEST_LOGS=true`). Oppretter øktmapper med nummererte filer: `1_req_client.json` → `7_res_client.txt`. All I/O er asynkron (fire-and-forget). Maskerer sensitive overskrifter. | -| `bypassHandler.ts` | Avskjærer spesifikke mønstre fra Claude CLI (tittelutvinning, oppvarming, telling) og returnerer falske svar uten å ringe noen leverandør. Støtter både streaming og ikke-streaming. Med vilje begrenset til Claude CLI-omfang. | -| `networkProxy.ts` | Løser utgående proxy-URL for en gitt leverandør med prioritet: leverandørspesifikk konfig → global konfig → miljøvariabler (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Støtter `NO_PROXY` ekskluderinger. Cacher konfigurasjon for 30s. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | #### SSE Streaming Pipeline @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Request Logger Session Struktur +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 applikasjonslag (`src/`) +### 4.7 Application Layer (`src/`) -| Katalog | Formål | -| ------------- | ------------------------------------------------------------------------- | -| `src/app/` | Web-UI, API-ruter, Express-mellomvare, OAuth-tilbakeringsbehandlere | -| `src/lib/` | Databasetilgang (`localDb.ts`, `usageDb.ts`), autentisering, delt | -| `src/mitm/` | Man-in-the-midten proxy-verktøy for å avskjære leverandørtrafikk | -| `src/models/` | Databasemodelldefinisjoner | -| `src/shared/` | Omslag rundt åpne-sse-funksjoner (leverandør, strøm, feil osv.) | -| `src/sse/` | SSE-endepunktbehandlere som kobler open-sse-biblioteket til Express-ruter | -| `src/store/` | Søknadstilstandsadministrasjon | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Bemerkelsesverdige API-ruter +#### Notable API Routes -| Rute | Metoder | Formål | -| --------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | GET/POST/SLETT | CRUD for tilpassede modeller per leverandør | -| `/api/models/catalog` | FÅ | Samlet katalog over alle modeller (chat, innebygging, bilde, tilpasset) gruppert etter leverandør | -| `/api/settings/proxy` | GET/SETT/SLETT | Hierarkisk utgående proxy-konfigurasjon (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | INNLEGG | Validerer proxy-tilkobling og returnerer offentlig IP/latency | -| `/v1/providers/[provider]/chat/completions` | INNLEGG | Dedikerte chatfullføringer per leverandør med modellvalidering | -| `/v1/providers/[provider]/embeddings` | INNLEGG | Dedikerte innbygginger per leverandør med modellvalidering | -| `/v1/providers/[provider]/images/generations` | INNLEGG | Dedikert bildegenerering per leverandør med modellvalidering | -| `/api/settings/ip-filter` | GET/SETT | IP-godkjenningsliste/blokkeringslisteadministrasjon | -| `/api/settings/thinking-budget` | GET/SETT | Begrunnelse token budsjettkonfigurasjon (passthrough/auto/custom/adaptive) | -| `/api/settings/system-prompt` | GET/SETT | Global systemprompt injeksjon for alle forespørsler | -| `/api/sessions` | FÅ | Aktiv øktsporing og beregninger | -| `/api/rate-limits` | FÅ | Satsgrensestatus per konto | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Nøkkeldesignmønstre +## 5. Key Design Patterns -### 5.1 Hub-and-Speake-oversettelse +### 5.1 Hub-and-Spoke Translation -Alle formater oversettes gjennom **OpenAI-formatet som navet**. Å legge til en ny leverandør krever bare å skrive **ett par** med oversettere (til/fra OpenAI), ikke N par. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Eksekutørstrategimønster +### 5.2 Executor Strategy Pattern -Hver leverandør har en dedikert eksekutørklasse som arver fra `BaseExecutor`. Fabrikken i `executors/index.ts` velger den riktige ved kjøring. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Selvregistrerende pluginsystem +### 5.3 Self-Registering Plugin System -Oversettermoduler registrerer seg ved import via `register()`. Å legge til en ny oversetter er bare å lage en fil og importere den. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Kontotilbakeslag med eksponentiell backoff +### 5.4 Account Fallback with Exponential Backoff -Når en leverandør returnerer 429/401/500, kan systemet bytte til neste konto ved å bruke eksponentielle nedkjølinger (1s → 2s → 4s → maks 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Combo modellkjeder +### 5.5 Combo Model Chains -En "combo" grupperer flere `provider/model` strenger. Hvis den første mislykkes, fall tilbake til den neste automatisk. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Stateful streaming-oversettelse +### 5.6 Stateful Streaming Translation -Responsoversettelse opprettholder tilstanden på tvers av SSE-biter (tenkeblokksporing, akkumulering av verktøykall, indeksering av innholdsblokker) via `initState()`-mekanismen. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Brukssikkerhetsbuffer +### 5.7 Usage Safety Buffer -En buffer på 2000 tokener legges til rapportert bruk for å hindre klienter i å nå grensene for kontekstvindu på grunn av overhead fra systemforespørsler og formatoversettelse. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Støttede formater +## 6. Supported Formats -| Format | Retning | Identifikator | -| ------------------------ | ----------- | ------------------ | -| OpenAI Chat-fullføringer | kilde + mål | `openai` | -| OpenAI Responses API | kilde + mål | `openai-responses` | -| Antropiske Claude | kilde + mål | `claude` | -| Google Gemini | kilde + mål | `gemini` | -| Google Gemini CLI | kun mål | `gemini-cli` | -| Antigravitasjon | kilde + mål | `antigravity` | -| AWS Kiro | kun mål | `kiro` | -| Markør | kun mål | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Støttede leverandører +## 7. Supported Providers -| Leverandør | Auth metode | Utfører | Nøkkelnotater | -| ------------------------ | ------------------------- | --------------- | ---------------------------------------------------------------------------- | -| Antropiske Claude | API-nøkkel eller OAuth | Standard | Bruker `x-api-key` header | -| Google Gemini | API-nøkkel eller OAuth | Standard | Bruker `x-goog-api-key` header | -| Google Gemini CLI | OAuth | GeminiCLI | Bruker `streamGenerateContent` endepunkt | -| Antigravitasjon | OAuth | Antigravitasjon | Tilbakestilling av flere nettadresser, egendefinert prøv å analysere på nytt | -| OpenAI | API-nøkkel | Standard | Standard bærer auth | -| Codex | OAuth | Codex | Injiserer systeminstruksjoner, styrer tenkning | -| GitHub Copilot | OAuth + Copilot-token | Github | Dobbelt token, VSCode header-etterligning | -| Kiro (AWS) | AWS SSO OIDC eller Social | Kiro | Binær EventStream-parsing | -| Markør IDE | Sjekksum auth | Markør | Protobuf-koding, SHA-256 kontrollsummer | -| Qwen | OAuth | Standard | Standard auth | -| iFlow | OAuth (Basic + Bearer) | Standard | Dobbel autentiseringshode | -| OpenRouter | API-nøkkel | Standard | Standard bærer auth | -| GLM, Kimi, MiniMax | API-nøkkel | Standard | Claude-kompatibel, bruk `x-api-key` | -| `openai-compatible-*` | API-nøkkel | Standard | Dynamisk: ethvert OpenAI-kompatibelt endepunkt | -| `anthropic-compatible-*` | API-nøkkel | Standard | Dynamisk: ethvert Claude-kompatibelt endepunkt | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Dataflytsammendrag +## 8. Data Flow Summary -### Strømmeforespørsel +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Ikke-streamende forespørsel +### Non-Streaming Request ```mermaid flowchart LR diff --git a/docs/i18n/no/FEATURES.md b/docs/i18n/no/FEATURES.md index 0b57b35fef..82cc73b67b 100644 --- a/docs/i18n/no/FEATURES.md +++ b/docs/i18n/no/FEATURES.md @@ -1,22 +1,22 @@ -# OmniRoute — Dashboard-funksjonsgalleri +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Visuell veiledning til hver del av OmniRoute-dashbordet. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Leverandører +## 🔌 Providers -Administrer AI-leverandørtilkoblinger: OAuth-leverandører (Claude Code, Codex, Gemini CLI), API-nøkkelleverandører (Groq, DeepSeek, OpenRouter) og gratisleverandører (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Kombinasjoner +## 🎨 Combos -Lag modellrutingskombinasjoner med 6 strategier: fyll-først, round-robin, kraft-av-to-valg, tilfeldig, minst brukt og kostnadsoptimalisert. Hver kombinasjon kjeder flere modeller med automatisk fallback. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) @@ -24,54 +24,119 @@ Lag modellrutingskombinasjoner med 6 strategier: fyll-først, round-robin, kraft ## 📊 Analytics -Omfattende bruksanalyse med symbolforbruk, kostnadsestimater, aktivitetsvarmekart, ukentlige distribusjonsdiagrammer og sammenbrudd per leverandør. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Systemhelse +## 🏥 System Health -Sanntidsovervåking: oppetid, minne, versjon, latenspersentiler (p50/p95/p99), hurtigbufferstatistikk og leverandørens strømbrytertilstander. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Oversetter Lekeplass +## 🔧 Translator Playground -Fire moduser for feilsøking av API-oversettelser: **Lekeplass** (formatkonvertering), **Chattester** (liveforespørsler), **Testbenk** (batch-tester) og **Live Monitor** (sanntidsstrøm). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Innstillinger +## 🎮 Model Playground _(v2.0.9+)_ -Generelle innstillinger, systemlagring, administrasjon av sikkerhetskopiering (eksport-/importdatabase), utseende (mørk/lysmodus), sikkerhet (inkluderer API-endepunktsbeskyttelse og blokkering av tilpasset leverandør), ruting, robusthet og avansert konfigurasjon. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI-verktøy +## 🔧 CLI Tools -Ett-klikks konfigurasjon for AI-kodeverktøy: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code og Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Forespørselslogger +## 🤖 CLI Agents _(v2.0.11+)_ -Forespørselslogging i sanntid med filtrering etter leverandør, modell, konto og API-nøkkel. Viser statuskoder, tokenbruk, ventetid og svardetaljer. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API-endepunkt +## 🌐 API Endpoint -Ditt enhetlige API-endepunkt med funksjonsoversikt: Chatfullføringer, innebygginger, bildegenerering, omrangering, lydtranskripsjon og registrerte API-nøkler. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/no/TROUBLESHOOTING.md b/docs/i18n/no/TROUBLESHOOTING.md index 6ab8a28ca4..120092d63c 100644 --- a/docs/i18n/no/TROUBLESHOOTING.md +++ b/docs/i18n/no/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Feilsøking +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Vanlige problemer og løsninger for OmniRoute. +Common problems and solutions for OmniRoute. --- -## Hurtigrettinger +## Quick Fixes -| Problem | Løsning | -| -------------------------------------- | -------------------------------------------------------------------- | -| Første pålogging fungerer ikke | Sjekk `INITIAL_PASSWORD` i `.env` (standard: `123456`) | -| Dashboard åpnes på feil port | Sett `PORT=20128` og `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Ingen forespørselslogger under `logs/` | Sett `ENABLE_REQUEST_LOGS=true` | -| EACCES: tillatelse nektet | Sett `DATA_DIR=/path/to/writable/dir` til å overstyre `~/.omniroute` | -| Rutingstrategi lagrer ikke | Oppdater til v1.4.11+ (Zod-skjemafiks for varighet av innstillinger) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Leverandørproblemer +## Provider Issues -### "Språkmodellen ga ikke meldinger" +### "Language model did not provide messages" -**Årsak:** Leverandørkvoten er oppbrukt. +**Cause:** Provider quota exhausted. -**Fiks:** +**Fix:** -1. Sjekk dashbordkvotesporing -2. Bruk en kombinasjon med reservelag -3. Bytt til billigere/gratis lag +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Satsbegrensning +### Rate Limiting -**Årsak:** Abonnementskvoten er oppbrukt. +**Cause:** Subscription quota exhausted. -**Fiks:** +**Fix:** -- Legg til reserve: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Bruk GLM/MiniMax som billig backup +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth-token utløpt +### OAuth Token Expired -OmniRoute oppdaterer tokens automatisk. Hvis problemene vedvarer: +OmniRoute auto-refreshes tokens. If issues persist: -1. Dashboard → Leverandør → Koble til på nytt -2. Slett og legg til leverandørtilkoblingen på nytt +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Skyproblemer +## Cloud Issues -### Skysynkroniseringsfeil +### Cloud Sync Errors -1. Bekreft `BASE_URL` poeng til løpeforekomsten din (f.eks. `http://localhost:20128`) -2. Bekreft `CLOUD_URL` poeng til skyendepunktet ditt (f.eks. `https://omniroute.dev`) -3. Hold `NEXT_PUBLIC_*` verdier på linje med verdiene på tjenersiden +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Returnerer 500 +### Cloud `stream=false` Returns 500 -**Symptom:** `Unexpected token 'd'...` på nettskyendepunkt for samtaler som ikke strømmer. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Årsak:** Oppstrøms returnerer SSE-nyttelast mens klienten forventer JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Løsning:** Bruk `stream=true` for direkte sky-anrop. Lokal kjøretid inkluderer SSE→JSON reserve. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud sier tilkoblet, men "Ugyldig API-nøkkel" +### Cloud Says Connected but "Invalid API key" -1. Lag en ny nøkkel fra lokalt dashbord (`/api/keys`) -2. Kjør skysynkronisering: Aktiver Cloud → Synkroniser nå -3. Gamle/ikke-synkroniserte nøkler kan fortsatt returnere `401` på skyen +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Docker-problemer +## Docker Issues -### CLI-verktøyet viser ikke installert +### CLI Tool Shows Not Installed -1. Sjekk kjøretidsfelt: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. For bærbar modus: bruk bildemål `runner-cli` (medfølgende CLI-er) -3. For vertsmonteringsmodus: sett `CLI_EXTRA_PATHS` og monter vertsbokskatalogen som skrivebeskyttet -4. Hvis `installed=true` og `runnable=false`: binær ble funnet, men mislyktes i helsesjekken +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Rask kjøretidsvalidering +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Kostnadsproblemer +## Cost Issues -### Høye kostnader +### High Costs -1. Sjekk bruksstatistikk i Dashboard → Bruk -2. Bytt primærmodell til GLM/MiniMax -3. Bruk gratis nivå (Gemini CLI, iFlow) for ikke-kritiske oppgaver -4. Angi kostnadsbudsjetter per API-nøkkel: Dashboard → API-nøkler → Budsjett +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Feilsøking +## Debugging -### Aktiver forespørselslogger +### Enable Request Logs -Sett `ENABLE_REQUEST_LOGS=true` i filen `.env`. Logger vises under katalogen `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Sjekk leverandørens helse +### Check Provider Health ```bash # Health dashboard @@ -120,100 +120,135 @@ curl http://localhost:20128/api/monitoring/health ### Runtime Storage -- Hovedtilstand: `${DATA_DIR}/db.json` (leverandører, kombinasjoner, aliaser, nøkler, innstillinger) -- Bruk: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Forespørselslogger: `/logs/...` (når `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Strømbryterproblemer +## Circuit Breaker Issues -### Leverandøren sitter fast i ÅPEN tilstand +### Provider stuck in OPEN state -Når en leverandørs strømbryter er ÅPEN, blokkeres forespørsler til nedkjølingen utløper. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Fiks:** +**Fix:** -1. Gå til **Dashboard → Innstillinger → Resiliens** -2. Sjekk kretsbryterkortet for den berørte leverandøren -3. Klikk på **Tilbakestill alle** for å fjerne alle brytere, eller vent til nedkjølingen utløper -4. Bekreft at leverandøren faktisk er tilgjengelig før du tilbakestiller +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Leverandøren fortsetter å utløse strømbryteren +### Provider keeps tripping the circuit breaker -Hvis en leverandør gjentatte ganger går inn i ÅPEN tilstand: +If a provider repeatedly enters OPEN state: -1. Sjekk **Dashboard → Helse → Leverandørhelse** for feilmønsteret -2. Gå til **Innstillinger → Resiliens → Leverandørprofiler** og øk feilterskelen -3. Sjekk om leverandøren har endret API-grenser eller krever re-autentisering -4. Se gjennom latenstidstelemetri – høy latenstid kan forårsake timeout-baserte feil +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problemer med lydtranskripsjon +## Audio Transcription Issues -### "Ustøttet modell"-feil +### "Unsupported model" error -- Sørg for at du bruker riktig prefiks: `deepgram/nova-3` eller `assemblyai/best` -- Bekreft at leverandøren er tilkoblet i **Dashboard → Leverandører** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Transkripsjon returnerer tom eller mislykkes +### Transcription returns empty or fails -- Sjekk støttede lydformater: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Bekreft at filstørrelsen er innenfor leverandørens grenser (vanligvis < 25 MB) -- Sjekk gyldigheten av leverandørens API-nøkkel i leverandørkortet +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Oversetter feilsøking +## Translator Debugging -Bruk **Dashboard → Oversetter** for å feilsøke problemer med formatoversettelse: +Use **Dashboard → Translator** to debug format translation issues: -| Modus | Når skal du bruke | -| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -| **Lekeplass** | Sammenlign input/output formater side ved side — lim inn en mislykket forespørsel for å se hvordan den oversettes | -| **Chattetester** | Send direktemeldinger og inspiser hele nyttelasten for forespørsel/svar inkludert overskrifter | -| **Testbenk** | Kjør batch-tester på tvers av formatkombinasjoner for å finne hvilke oversettelser som er ødelagte | -| **Live Monitor** | Se forespørselsflyt i sanntid for å fange opp periodiske oversettelsesproblemer | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Vanlige formatproblemer +### Common format issues -- **Tenkekoder vises ikke** — Sjekk om målleverandøren støtter tenkning og innstillingen av tenkebudsjettet -- **Verktøyanrop dropper** — Noen formatoversettelser kan fjerne felt som ikke støttes; verifisere i Playground-modus -- **Systemmelding mangler** — Claude og Gemini håndterer systemmeldinger annerledes; sjekk oversettelsen -- **SDK returnerer rå streng i stedet for objekt** — Rettet i v1.1.0: svarrenser fjerner nå ikke-standard felt (`x_groq`, `usage_breakdown`, etc.) som forårsaker OpenAI SDK Pydantic valideringsfeil -- **GLM/ERNIE avviser rollen `system`** — Rettet i v1.1.0: rollenormalisering slår automatisk sammen systemmeldinger til brukermeldinger for inkompatible modeller -- **`developer` rolle ikke gjenkjent** — Rettet i v1.1.0: automatisk konvertert til `system` for ikke-OpenAI-leverandører -- **`json_schema` fungerer ikke med Gemini** — Rettet i v1.1.0: `response_format` er nå konvertert til Geminis `responseMimeType` + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Resiliensinnstillinger +## Resilience Settings -### Auto rate-limit utløses ikke +### Auto rate-limit not triggering -- Automatisk takstgrense gjelder bare API-nøkkelleverandører (ikke OAuth/abonnement) -- Bekreft at **Innstillinger → Resiliens → Leverandørprofiler** har aktivert automatisk satsgrense -- Sjekk om leverandøren returnerer `429` statuskoder eller `Retry-After` overskrifter +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Tuning eksponentiell backoff +### Tuning exponential backoff -Leverandørprofiler støtter disse innstillingene: +Provider profiles support these settings: -- **Basisforsinkelse** — Innledende ventetid etter første feil (standard: 1 s) -- **Maks. forsinkelse** — Maksimal ventetid (standard: 30s) -- **Multiplikator** — Hvor mye skal forsinkelsen økes per påfølgende feil (standard: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Anti-tordenflokk +### Anti-thundering herd -Når mange samtidige forespørsler treffer en hastighetsbegrenset leverandør, bruker OmniRoute mutex + automatisk hastighetsbegrensning for å serialisere forespørsler og forhindre kaskadefeil. Dette er automatisk for API-nøkkelleverandører. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Fortsatt fast? +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub-problemer**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arkitektur**: Se [link](ARCHITECTURE.md) for interne detaljer -- **API-referanse**: Se [link](API_REFERENCE.md) for alle endepunkter -- **Helse Dashboard**: Sjekk **Dashboard → Health** for sanntids systemstatus -- **Oversetter**: Bruk **Dashboard → Oversetter** for å feilsøke formatproblemer +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/no/USER_GUIDE.md b/docs/i18n/no/USER_GUIDE.md index 19775dc668..5a043224df 100644 --- a/docs/i18n/no/USER_GUIDE.md +++ b/docs/i18n/no/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Brukerveiledning +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Komplett veiledning for å konfigurere leverandører, lage kombinasjoner, integrere CLI-verktøy og distribuere OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Innholdsfortegnelse +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Komplett veiledning for å konfigurere leverandører, lage kombinasjoner, integr --- -## 💰 Priser på et øyeblikk +## 💰 Pricing at a Glance -| Nivå | Leverandør | Kostnad | Kvote Tilbakestill | Best for | -| ----------------- | ----------------- | --------------- | ----------------------- | ------------------------ | -| **💳 ABONNEMENT** | Claude Code (Pro) | $20/md | 5t + ukentlig | Allerede abonnert | -| | Codex (Pluss/Pro) | $20-200/md | 5t + ukentlig | OpenAI-brukere | -| | Gemini CLI | **GRATIS** | 180K/mnd + 1K/dag | Alle sammen! | -| | GitHub Copilot | $10-19/md | Månedlig | GitHub-brukere | -| **🔑 API NØKKEL** | DeepSeek | Betal per bruk | Ingen | Billig resonnement | -| | Groq | Betal per bruk | Ingen | Ultrarask slutning | -| | xAI (Grok) | Betal per bruk | Ingen | Grok 4 resonnement | -| | Mistral | Betal per bruk | Ingen | EU-vertsbaserte modeller | -| | Forvirring | Betal per bruk | Ingen | Søkeutvidet | -| | Sammen AI | Betal per bruk | Ingen | Åpen kildekode-modeller | -| | Fyrverkeri AI | Betal per bruk | Ingen | Rask FLUX bilder | -| | Cerebras | Betal per bruk | Ingen | Wafer-skala hastighet | -| | Sammenheng | Betal per bruk | Ingen | Kommando R+ RAG | -| | NVIDIA NIM | Betal per bruk | Ingen | Bedriftsmodeller | -| **💰 BILLIG** | GLM-4.7 | $0,6/1M | Daglig 10:00 | Budsjett backup | -| | MiniMax M2.1 | $0,2/1 million | 5-timers rullende | Billigste alternativ | -| | Kimi K2 | $9/md leilighet | 10 millioner tokens/mnd | Forutsigbar kostnad | -| **🆓 GRATIS** | iFlow | $0 | Ubegrenset | 8 modeller gratis | -| | Qwen | $0 | Ubegrenset | 3 modeller gratis | -| | Kiro | $0 | Ubegrenset | Claude gratis | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Profftips:** Start med Gemini CLI (180K gratis/måned) + iFlow (ubegrenset gratis) kombinasjon = $0 kostnad! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Brukssaker +## 🎯 Use Cases -### Sak 1: "Jeg har Claude Pro-abonnement" +### Case 1: "I have Claude Pro subscription" -**Problem:** Kvoten utløper ubrukt, satsgrenser under tung koding +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Tilfelle 2: "Jeg vil ha null kostnad" +### Case 2: "I want zero cost" -**Problem:** Har ikke råd til abonnementer, trenger pålitelig AI-koding +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Tilfelle 3: "Jeg trenger 24/7 koding, ingen avbrudd" +### Case 3: "I need 24/7 coding, no interruptions" -**Problem:** Tidsfrister, har ikke råd til nedetid +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Tilfelle 4: "Jeg vil ha GRATIS AI i OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Problem:** Trenger AI-assistent i meldingsapper, helt gratis +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Leverandøroppsett +## 📖 Provider Setup -### 🔐 Abonnementsleverandører +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Profftips:** Bruk Opus for komplekse oppgaver, Sonnet for hastighet. OmniRoute sporer kvote per modell! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (GRATIS 180K/måned!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,7 +152,7 @@ Models: gc/gemini-2.5-pro ``` -**Mest verdi:** Enormt gratis nivå! Bruk dette før betalte nivåer. +**Best Value:** Huge free tier! Use this before paid tiers. #### GitHub Copilot @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Billige leverandører +### 💰 Cheap Providers -#### GLM-4.7 (Daglig tilbakestilling, $0,6/1M) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Registrer deg: [Zhipu AI](https://open.bigmodel.cn/) -2. Få API-nøkkel fra Coding Plan -3. Dashboard → Legg til API-nøkkel: Leverandør: `glm`, API-nøkkel: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Bruk:** `glm/glm-4.7` — **Profftips:** Kodeplan tilbyr 3× kvote til 1/7 kostnad! Tilbakestill daglig 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5t tilbakestilling, $0,20/1M) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Registrer deg: [MiniMax](https://www.minimax.io/) -2. Hent API-nøkkel → Dashboard → Legg til API-nøkkel +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Bruk:** `minimax/MiniMax-M2.1` — **Profftips:** Billigste alternativet for lang kontekst (1M tokens)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/mnd leilighet) +#### Kimi K2 ($9/month flat) -1. Abonner: [Moonshot AI](https://platform.moonshot.ai/) -2. Hent API-nøkkel → Dashboard → Legg til API-nøkkel +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Bruk:** `kimi/kimi-latest` — **Profftips:** Fast $9/måned for 10M tokens = $0,90/1M effektiv kostnad! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 GRATIS Leverandører +### 🆓 FREE Providers -#### iFlow (8 GRATIS modeller) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 GRATIS modeller) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRATIS) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Kombinasjoner +## 🎨 Combos -### Eksempel 1: Maksimer abonnement → Billig sikkerhetskopi +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Eksempel 2: Kun gratis (nullkostnad) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI-integrasjon +## 🔧 CLI Integration -### Markør IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -262,7 +262,7 @@ Settings → Models → Advanced: ### Claude Code -Rediger `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Rediger `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Rediger `~/.openclaw/openclaw.json`: } ``` -**Eller bruk Dashboard:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Fortsett / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Utrulling +## 🚀 Deployment -### VPS-distribusjon +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -For vertsintegrert modus med CLI-binærfiler, se Docker-delen i hoveddokumentene. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Miljøvariabler +### Environment Variables -| Variabel | Standard | Beskrivelse | -| --------------------- | ------------------------------------ | ---------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signeringshemmelighet (**endring i produksjon**) | -| `INITIAL_PASSWORD` | `123456` | Første påloggingspassord | -| `DATA_DIR` | `~/.omniroute` | Datakatalog (db, bruk, logger) | -| `PORT` | standard rammeverk | Tjenesteport (`20128` i eksempler) | -| `HOSTNAME` | standard rammeverk | Bind vert (Docker er standard til `0.0.0.0`) | -| `NODE_ENV` | kjøretidsstandard | Sett `production` for distribusjon | -| `BASE_URL` | `http://localhost:20128` | Intern basis-URL på tjenersiden | -| `CLOUD_URL` | `https://omniroute.dev` | Nettadresse for endepunkt for nettskysynkronisering | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC-hemmelighet for genererte API-nøkler | -| `REQUIRE_API_KEY` | `false` | Håndhev Bearer API-nøkkel på `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Aktiverer forespørsels-/svarlogger | -| `AUTH_COOKIE_SECURE` | `false` | Tving `Secure` auth-informasjonskapsel (bak HTTPS omvendt proxy) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -For hele miljøvariabelreferansen, se [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Tilgjengelige modeller +## 📊 Available Models
-Se alle tilgjengelige modeller +View all available models -**Claude-kode (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Kodeks (`cx/`)** — Pluss/Proff: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — $0,6/1M: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $0,2/1M: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,7 +460,7 @@ For hele miljøvariabelreferansen, se [README](../README.md). **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Forvirring (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` **Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` @@ -409,7 +468,7 @@ For hele miljøvariabelreferansen, se [README](../README.md). **Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Kohere (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ For hele miljøvariabelreferansen, se [README](../README.md). --- -## 🧩 Avanserte funksjoner +## 🧩 Advanced Features -### Egendefinerte modeller +### Custom Models -Legg til hvilken som helst modell-ID til en hvilken som helst leverandør uten å vente på en appoppdatering: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Eller bruk Dashboard: **Leverandører → [Leverandør] → Egendefinerte modeller**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Dedikerte leverandørruter +### Dedicated Provider Routes -Rute forespørsler direkte til en spesifikk leverandør med modellvalidering: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,7 +504,7 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Leverandørprefikset blir automatisk lagt til hvis det mangler. Umatchede modeller returnerer `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. ### Network Proxy Configuration @@ -463,7 +522,7 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Forrang:** Nøkkelspesifikk → Kombinasjonsspesifikk → Leverandørspesifikk → Global → Miljø. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. ### Model Catalog API @@ -471,68 +530,68 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ curl http://localhost:20128/api/models/catalog ``` -Returnerer modeller gruppert etter leverandør med typer (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). ### Cloud Sync -- Synkroniser leverandører, kombinasjoner og innstillinger på tvers av enheter -- Automatisk bakgrunnssynkronisering med timeout + feil-rask -- Foretrekk server-side `BASE_URL`/`CLOUD_URL` i produksjon +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (fase 9) +### LLM Gateway Intelligence (Phase 9) -- **Semantisk hurtigbuffer** — Automatisk hurtigbufring uten strømming, temperatur=0 svar (omgå med `X-OmniRoute-No-Cache: true`) -- **Request Idempotency** — Dedupliserer forespørsler innen 5 sekunder via `Idempotency-Key` eller `X-Request-Id` header -- **Fremdriftssporing** — Meld deg på SSE `event: progress` hendelser via `X-OmniRoute-Progress: true` header +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Oversetter Lekeplass +### Translator Playground -Tilgang via **Dashboard → Oversetter**. Feilsøk og visualiser hvordan OmniRoute oversetter API-forespørsler mellom leverandører. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Modus | Formål | -| ---------------- | ------------------------------------------------------------------------------------------------ | -| **Lekeplass** | Velg kilde-/målformater, lim inn en forespørsel og se den oversatte utgangen umiddelbart | -| **Chattetester** | Send live chat-meldinger gjennom proxyen og inspiser hele forespørsels-/svarsyklusen | -| **Testbenk** | Kjør batch-tester på tvers av flere formatkombinasjoner for å bekrefte oversettelsens korrekthet | -| **Live Monitor** | Se sanntidsoversettelser mens forespørsler strømmer gjennom proxyen | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Brukstilfeller:** +**Use cases:** -- Feilsøk hvorfor en spesifikk klient/leverandør-kombinasjon mislykkes -- Bekreft at tankekoder, verktøykall og systemmeldinger oversettes riktig -- Sammenlign formatforskjeller mellom OpenAI, Claude, Gemini og Responses API-formater +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Rutingstrategier +### Routing Strategies -Konfigurer via **Dashboard → Innstillinger → Ruting**. +Configure via **Dashboard → Settings → Routing**. -| Strategi | Beskrivelse | -| ------------------------------ | -------------------------------------------------------------------------------------------------------- | -| **Fyll først** | Bruker kontoer i prioritert rekkefølge — primærkonto håndterer alle forespørsler inntil utilgjengelig | -| **Round Robin** | Bla gjennom alle kontoer med en konfigurerbar klebrig grense (standard: 3 samtaler per konto) | -| **P2C (Power of Two Choices)** | Velger 2 tilfeldige kontoer og ruter til den sunnere — balanserer belastning med bevissthet om helse | -| **Tilfeldig** | Velger tilfeldig en konto for hver forespørsel ved hjelp av Fisher-Yates shuffle | -| **Minst brukt** | Ruter til kontoen med det eldste `lastUsedAt` tidsstemplet, fordeler trafikk jevnt | -| **Kostnadsoptimalisert** | Ruter til kontoen med den laveste prioritetsverdien, optimalisering for de laveste kostnadsleverandørene | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Jokertegn modellaliaser +#### Wildcard Model Aliases -Lag jokertegnmønstre for å tilordne modellnavn på nytt: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Jokertegn støtter `*` (alle tegn) og `?` (enkelttegn). +Wildcards support `*` (any characters) and `?` (single character). -#### Reservekjeder +#### Fallback Chains -Definer globale reservekjeder som gjelder for alle forespørsler: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Spenst og effektbrytere +### Resilience & Circuit Breakers -Konfigurer via **Dashboard → Innstillinger → Resiliens**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementerer motstandskraft på leverandørnivå med fire komponenter: +OmniRoute implements provider-level resilience with four components: -1. **Leverandørprofiler** — Konfigurasjon per leverandør for: - - Feilterskel (hvor mange feil før åpning) - - Nedkjølingsvarighet - - Følsomhet for deteksjon av hastighetsgrense - - Eksponentielle backoff-parametere +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Redigerbare rategrenser** — Standardinnstillinger på systemnivå som kan konfigureres i dashbordet: - - **Forespørsler per minutt (RPM)** — Maksimalt antall forespørsler per minutt per konto - - **Min time Between Requests** — Minimumsavstand i millisekunder mellom forespørsler - - **Maks samtidige forespørsler** — Maksimalt antall samtidige forespørsler per konto - - Klikk på **Rediger** for å endre, deretter **Lagre** eller **Avbryt**. Verdiene vedvarer via resilience API. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** — Sporer feil per leverandør og åpner automatisk kretsen når en terskel er nådd: - - **STENGT** (Sunn) — Forespørslene flyter normalt - - **ÅPEN** — Leverandøren er midlertidig blokkert etter gjentatte feil - - **HALF_OPEN** — Tester om leverandøren har kommet seg +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Retningslinjer og låste identifikatorer** — Viser strømbryterstatus og låste identifikatorer med tvangsopplåsingsfunksjon. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Rate Limit Auto-Detection** — Overvåker `429` og `Retry-After` overskrifter for å proaktivt unngå å treffe leverandørens takstgrenser. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Profftips:** Bruk **Tilbakestill alle**-knappen for å fjerne alle strømbrytere og nedkjøling når en leverandør kommer seg etter et strømbrudd. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Databaseeksport/import +### Database Export / Import -Administrer sikkerhetskopiering av databaser i **Dashboard → Innstillinger → System og lagring**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Handling | Beskrivelse | -| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Eksporter database** | Laster ned gjeldende SQLite-database som en `.sqlite`-fil | -| **Eksporter alle (.tar.gz)** | Laster ned et fullstendig sikkerhetskopiarkiv inkludert: database, innstillinger, kombinasjoner, leverandørtilkoblinger (ingen legitimasjon), API-nøkkelmetadata | -| **Importer database** | Last opp en `.sqlite`-fil for å erstatte gjeldende database. En forhåndsimport-sikkerhetskopi opprettes automatisk | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Importvalidering:** Den importerte filen er validert for integritet (SQLite pragmasjekk), nødvendige tabeller (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) og størrelse (maks 100 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Brukstilfeller:** +**Use Cases:** -- Migrer OmniRoute mellom maskiner -- Lag eksterne sikkerhetskopier for katastrofegjenoppretting -- Del konfigurasjoner mellom teammedlemmer (eksporter alle → del arkiv) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Innstillinger Dashboard +### Settings Dashboard -Innstillingssiden er organisert i 5 faner for enkel navigering: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Innhold | -| ------------- | ----------------------------------------------------------------------------------------------------------------- | -| **Sikkerhet** | Innstillinger for pålogging/passord, IP-tilgangskontroll, API-autentisering for `/models` og leverandørblokkering | -| **Ruting** | Global rutingstrategi (6 alternativer), jokertegnmodellaliaser, reservekjeder, kombinasjonsstandarder | -| **Resiliens** | Leverandørprofiler, redigerbare hastighetsgrenser, strømbryterstatus, retningslinjer og låste identifikatorer | -| **AI** | Tenker budsjettkonfigurasjon, global systempromptinjeksjon, promptbufferstatistikk | -| **Avansert** | Global proxy-konfigurasjon (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Kostnader og budsjettstyring +### Costs & Budget Management -Tilgang via **Dashboard → Kostnader**. +Access via **Dashboard → Costs**. -| Tab | Formål | -| ------------ | ------------------------------------------------------------------------------------------------ | -| **Budsjett** | Angi utgiftsgrenser per API-nøkkel med daglige/ukentlige/månedlige budsjetter og sanntidssporing | -| **Pris** | Se og rediger modellprisoppføringer — kostnad per 1K input/output tokens per leverandør | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Kostnadssporing:** Hver forespørsel logger tokenbruk og beregner kostnad ved hjelp av pristabellen. Se oversikter i **Dashboard → Bruk** etter leverandør, modell og API-nøkkel. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Lydtranskripsjon +### Audio Transcription -OmniRoute støtter lydtranskripsjon via det OpenAI-kompatible endepunktet: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Tilgjengelige leverandører: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Støttede lydformater: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Kombinasjonsbalanseringsstrategier +### Combo Balancing Strategies -Konfigurer balansering per kombinasjon i **Dashboard → Combos → Opprett/Rediger → Strategi**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategi | Beskrivelse | -| ------------------------ | ----------------------------------------------------------------------------------- | -| **Round-Robin** | Roterer gjennom modellene sekvensielt | -| **Prioritet** | Prøver alltid den første modellen; faller tilbake kun på feil | -| **Tilfeldig** | Velger en tilfeldig modell fra kombinasjonen for hver forespørsel | -| **Vektet** | Ruter proporsjonalt basert på tildelte vekter per modell | -| **Minst brukt** | Ruter til modellen med færrest nylige forespørsler (bruker kombinasjonsberegninger) | -| **Kostnadsoptimalisert** | Ruter til den billigste tilgjengelige modellen (bruker pristabell) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Globale kombinasjonsstandarder kan angis i **Dashboard → Innstillinger → Ruting → Combo-standarder**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Helse Dashboard +### Health Dashboard -Tilgang via **Dashboard → Helse**. Sanntids systemhelseoversikt med 6 kort: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Kort | Hva det viser | -| --------------------- | ------------------------------------------------------------- | -| **Systemstatus** | Oppetid, versjon, minnebruk, datakatalog | -| **Leverandørs helse** | Per leverandør effektbrytertilstand (lukket/åpen/halvåpen) | -| **Satsgrenser** | Aktive nedkjølingshastigheter per konto med gjenværende tid | -| **Aktive Lockouts** | Leverandører midlertidig blokkert av lockout-policyen | -| **Signaturbuffer** | Dedupliseringsbufferstatistikk (aktive nøkler, trefffrekvens) | -| **Latens-telemetri** | p50/p95/p99 latensaggregering per leverandør | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Profftips:** Helsesiden oppdateres automatisk hvert 10. sekund. Bruk kretsbryterkortet til å identifisere hvilke leverandører som har problemer. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/phi/API_REFERENCE.md b/docs/i18n/phi/API_REFERENCE.md index 7c7f7f399d..b795722c11 100644 --- a/docs/i18n/phi/API_REFERENCE.md +++ b/docs/i18n/phi/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Sanggunian ng API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Kumpletong sanggunian para sa lahat ng endpoint ng OmniRoute API. +Complete reference for all OmniRoute API endpoints. --- -## Talaan ng mga Nilalaman +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Kumpletong sanggunian para sa lahat ng endpoint ng OmniRoute API. --- -## Mga Pagkumpleto ng Chat +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Mga Custom na Header +### Custom Headers -| Header | Direksyon | Paglalarawan | -| ------------------------ | ---------- | --------------------------------------------------- | -| `X-OmniRoute-No-Cache` | Kahilingan | Itakda sa `true` upang i-bypass ang cache | -| `X-OmniRoute-Progress` | Kahilingan | Itakda sa `true` para sa mga kaganapan sa pag-unlad | -| `Idempotency-Key` | Kahilingan | Dedup key (5s window) | -| `X-Request-Id` | Kahilingan | Alternatibong susi sa pagtanggal | -| `X-OmniRoute-Cache` | Tugon | `HIT` o `MISS` (hindi nag-stream) | -| `X-OmniRoute-Idempotent` | Tugon | `true` kung i-deduplicate | -| `X-OmniRoute-Progress` | Tugon | `enabled` kung ang pagsubaybay sa pag-unlad sa | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Mga pag-embed +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Mga available na provider: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Pagbuo ng Larawan +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Mga available na provider: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Listahan ng mga Modelo +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Mga Endpoint ng Compatibility +## Compatibility Endpoints -| Paraan | Landas | Format | +| Method | Path | Format | | ------ | --------------------------- | ---------------------- | | POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Antropiko | -| POST | `/v1/responses` | Mga Tugon sa OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | | POST | `/v1/embeddings` | OpenAI | | POST | `/v1/images/generations` | OpenAI | -| KUMUHA | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Antropiko | -| KUMUHA | `/v1beta/models` | Gemini | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | | POST | `/v1beta/models/{...path}` | Gemini generateContent | | POST | `/v1/api/chat` | Ollama | -### Nakalaang Mga Ruta ng Provider +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,7 +129,7 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Ang prefix ng provider ay awtomatikong idinaragdag kung nawawala. Ang mga hindi tugmang modelo ay nagbabalik ng `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Halimbawa ng tugon: +Response example: ```json { @@ -162,154 +162,164 @@ Halimbawa ng tugon: --- -## Dashboard at Pamamahala +## Dashboard & Management -### Pagpapatotoo +### Authentication -| Endpoint | Paraan | Paglalarawan | -| ----------------------------- | ------- | --------------------------------- | -| `/api/auth/login` | POST | Mag-login | -| `/api/auth/logout` | POST | Logout | -| `/api/settings/require-login` | GET/PUT | Kailangang i-toggle ang pag-login | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Pamamahala ng Provider +### Provider Management -| Endpoint | Paraan | Paglalarawan | -| ---------------------------- | --------------- | ---------------------------------- | -| `/api/providers` | GET/POST | Maglista / gumawa ng mga provider | -| `/api/providers/[id]` | GET/PUT/DELETE | Pamahalaan ang isang provider | -| `/api/providers/[id]/test` | POST | Subukan ang koneksyon ng provider | -| `/api/providers/[id]/models` | KUMUHA | Maglista ng mga modelo ng provider | -| `/api/providers/validate` | POST | I-validate ang config ng provider | -| `/api/provider-nodes*` | Iba't ibang | Pamamahala ng node ng provider | -| `/api/provider-models` | GET/POST/DELETE | Mga custom na modelo | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Mga Daloy ng OAuth +### OAuth Flows -| Endpoint | Paraan | Paglalarawan | -| -------------------------------- | ----------- | ------------------------------- | -| `/api/oauth/[provider]/[action]` | Iba't ibang | OAuth na partikular sa provider | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Pagruruta at Config +### Routing & Config -| Endpoint | Paraan | Paglalarawan | -| --------------------- | ----------- | -------------------------------------- | -| `/api/models/alias` | GET/POST | Mga alyas ng modelo | -| `/api/models/catalog` | KUMUHA | Lahat ng modelo ayon sa provider + uri | -| `/api/combos*` | Iba't ibang | Pamamahala ng combo | -| `/api/keys*` | Iba't ibang | Pamamahala ng key ng API | -| `/api/pricing` | KUMUHA | Pagpepresyo ng modelo | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Paggamit at Analytics +### Usage & Analytics -| Endpoint | Paraan | Paglalarawan | -| --------------------------- | ------ | ------------------------------ | -| `/api/usage/history` | KUMUHA | Kasaysayan ng paggamit | -| `/api/usage/logs` | KUMUHA | Mga log ng paggamit | -| `/api/usage/request-logs` | KUMUHA | Mga log sa antas ng kahilingan | -| `/api/usage/[connectionId]` | KUMUHA | Paggamit sa bawat koneksyon | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Mga Setting +### Settings -| Endpoint | Paraan | Paglalarawan | -| ------------------------------- | ------- | ------------------------------ | -| `/api/settings` | GET/PUT | Mga pangkalahatang setting | -| `/api/settings/proxy` | GET/PUT | Network proxy config | -| `/api/settings/proxy/test` | POST | Subukan ang proxy na koneksyon | -| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | -| `/api/settings/thinking-budget` | GET/PUT | Rasoning token budget | -| `/api/settings/system-prompt` | GET/PUT | Global system prompt | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Pagsubaybay +### Monitoring -| Endpoint | Paraan | Paglalarawan | -| ------------------------ | ---------- | --------------------------------------- | -| `/api/sessions` | KUMUHA | Aktibong pagsubaybay sa session | -| `/api/rate-limits` | KUMUHA | Mga limitasyon sa rate ng bawat account | -| `/api/monitoring/health` | KUMUHA | Pagsusuri sa kalusugan | -| `/api/cache` | GET/DELETE | Mga istatistika ng cache / i-clear | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### I-backup at I-export/I-import +### Backup & Export/Import -| Endpoint | Paraan | Paglalarawan | -| --------------------------- | ------ | ----------------------------------------------------- | -| `/api/db-backups` | KUMUHA | Ilista ang mga available na backup | -| `/api/db-backups` | ILAGAY | Gumawa ng manu-manong backup | -| `/api/db-backups` | POST | Ibalik mula sa isang partikular na backup | -| `/api/db-backups/export` | KUMUHA | I-download ang database bilang .sqlite file | -| `/api/db-backups/import` | POST | Mag-upload ng .sqlite file upang palitan ang database | -| `/api/db-backups/exportAll` | KUMUHA | I-download ang buong backup bilang .tar.gz archive | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | ### Cloud Sync -| Endpoint | Paraan | Paglalarawan | -| ---------------------- | ----------- | ------------------------------ | -| `/api/sync/cloud` | Iba't ibang | Mga pagpapatakbo ng cloud sync | -| `/api/sync/initialize` | POST | Simulan ang pag-sync | -| `/api/cloud/*` | Iba't ibang | Pamamahala ng ulap | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | ### CLI Tools -| Endpoint | Paraan | Paglalarawan | -| ---------------------------------- | ------ | ------------------------ | -| `/api/cli-tools/claude-settings` | KUMUHA | Claude CLI status | -| `/api/cli-tools/codex-settings` | KUMUHA | Katayuan ng Codex CLI | -| `/api/cli-tools/droid-settings` | KUMUHA | Katayuan ng Droid CLI | -| `/api/cli-tools/openclaw-settings` | KUMUHA | Katayuan ng OpenClaw CLI | -| `/api/cli-tools/runtime/[toolId]` | KUMUHA | Generic na CLI runtime | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Kasama sa mga tugon ng CLI ang: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Mga Limitasyon sa Katatagan at Rate +### ACP Agents -| Endpoint | Paraan | Paglalarawan | -| ----------------------- | ------- | ------------------------------------------------- | -| `/api/resilience` | GET/PUT | Kumuha/mag-update ng mga profile ng resilience | -| `/api/resilience/reset` | POST | I-reset ang mga circuit breaker | -| `/api/rate-limits` | KUMUHA | Katayuan ng limitasyon sa rate ng bawat account | -| `/api/rate-limit` | KUMUHA | Configuration ng limitasyon sa pandaigdigang rate | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Mga Eval +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Endpoint | Paraan | Paglalarawan | -| ------------ | -------- | ------------------------------------------- | -| `/api/evals` | GET/POST | Maglista ng mga eval suite / run evaluation | +### Resilience & Rate Limits -### Mga Patakaran +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Endpoint | Paraan | Paglalarawan | -| --------------- | --------------- | ----------------------------------------- | -| `/api/policies` | GET/POST/DELETE | Pamahalaan ang mga patakaran sa pagruruta | +### Evals -### Pagsunod +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Endpoint | Paraan | Paglalarawan | -| --------------------------- | ------ | ----------------------------------- | -| `/api/compliance/audit-log` | KUMUHA | Log ng audit ng pagsunod (huling N) | +### Policies + +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | + +### Compliance + +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | ### v1beta (Gemini-Compatible) -| Endpoint | Paraan | Paglalarawan | -| -------------------------- | ------ | ------------------------------------------ | -| `/v1beta/models` | KUMUHA | Listahan ng mga modelo sa Gemini na format | -| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -Ang mga endpoint na ito ay sumasalamin sa format ng API ng Gemini para sa mga kliyenteng umaasa sa native na Gemini SDK compatibility. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. -### Mga Panloob / System API +### Internal / System APIs -| Endpoint | Paraan | Paglalarawan | -| --------------- | ------ | ---------------------------------------------------------------------- | -| `/api/init` | KUMUHA | Pagsusuri sa pagsisimula ng application (ginamit sa unang pagtakbo) | -| `/api/tags` | KUMUHA | Mga tag ng modelong katugma sa Ollama (para sa mga kliyente ng Ollama) | -| `/api/restart` | POST | I-trigger ang magandang pag-restart ng server | -| `/api/shutdown` | POST | Mag-trigger ng magandang pag-shutdown ng server | +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | -> **Tandaan:** Ang mga endpoint na ito ay panloob na ginagamit ng system o para sa Ollama client compatibility. Hindi sila karaniwang tinatawag ng mga end user. +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Transkripsyon ng Audio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -I-transcribe ang mga audio file gamit ang Deepgram o AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Kahilingan:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Tugon:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Mga sinusuportahang provider:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Mga sinusuportahang format:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Ollama Compatibility -Para sa mga kliyenteng gumagamit ng format ng API ng Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,7 +367,7 @@ POST /v1/api/chat GET /api/tags ``` -Awtomatikong isinasalin ang mga kahilingan sa pagitan ng Ollama at mga panloob na format. +Requests are automatically translated between Ollama and internal formats. --- @@ -368,7 +378,7 @@ Awtomatikong isinasalin ang mga kahilingan sa pagitan ng Ollama at mga panloob n GET /api/telemetry/summary ``` -**Tugon:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Badyet +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Availability ng Modelo +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Pagproseso ng Kahilingan +## Request Processing -1. Nagpapadala ang kliyente ng kahilingan sa `/v1/*` -2. Tumatawag ang tagapangasiwa ng ruta sa `handleChat`, `handleEmbedding`, `handleAudioTranscription`, o `handleImageGeneration` -3. Nalutas ang modelo (direktang provider/modelo o alias/combo) -4. Pinili ang mga kredensyal mula sa lokal na DB na may pagsasala ng availability ng account -5. Para sa chat: `handleChatCore` — format detection, translation, cache check, idempotency check -6. Nagpapadala ang tagapagpatupad ng provider ng upstream na kahilingan -7. Ang tugon ay isinalin pabalik sa format ng kliyente (chat) o ibinalik sa dati (mga pag-embed/mga larawan/audio) -8. Naitala ang paggamit/pag-log -9. Nalalapat ang Fallback sa mga error ayon sa combo rules +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Buong sanggunian sa arkitektura: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Pagpapatotoo +## Authentication -- Ang mga ruta ng dashboard (`/dashboard/*`) ay gumagamit ng `auth_token` cookie -- Gumagamit ang pag-login ng naka-save na hash ng password; fallback sa `INITIAL_PASSWORD` -- `requireLogin` toggleable sa pamamagitan ng `/api/settings/require-login` -- `/v1/*` ruta opsyonal na nangangailangan ng Bearer API key kapag `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/phi/ARCHITECTURE.md b/docs/i18n/phi/ARCHITECTURE.md index b1c3962dbf..258d62df53 100644 --- a/docs/i18n/phi/ARCHITECTURE.md +++ b/docs/i18n/phi/ARCHITECTURE.md @@ -1,71 +1,71 @@ # OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Huling na-update: 2026-02-18_ +_Last updated: 2026-03-04_ ## Executive Summary -Ang OmniRoute ay isang lokal na AI routing gateway at dashboard na binuo sa Next.js. -Nagbibigay ito ng isang endpoint na katugma sa OpenAI (`/v1/*`) at niruruta ang trapiko sa maraming upstream provider na may pagsasalin, fallback, pag-refresh ng token, at pagsubaybay sa paggamit. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Mga pangunahing kakayahan: +Core capabilities: -- OpenAI-compatible na API surface para sa CLI/tools (28 provider) -- Kahilingan/tugon sa pagsasalin sa mga format ng provider -- Modelong combo fallback (multi-model sequence) -- Account-level fallback (multi-account bawat provider) -- Pamamahala ng koneksyon ng provider ng OAuth + API-key -- Pag-embed ng henerasyon sa pamamagitan ng `/v1/embeddings` (6 na provider, 9 na modelo) -- Pagbuo ng larawan sa pamamagitan ng `/v1/images/generations` (4 na provider, 9 na modelo) -- Isipin ang pag-parse ng tag (`...`) para sa mga modelo ng pangangatwiran -- Response sanitization para sa mahigpit na OpenAI SDK compatibility -- Pag-normalize ng tungkulin (developer→system, system→user) para sa cross-provider compatibility +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility - Structured output conversion (json_schema → Gemini responseSchema) -- Lokal na pagtitiyaga para sa mga provider, key, alias, combo, setting, pagpepresyo -- Pagsubaybay sa paggamit/gastos at pag-log ng kahilingan -- Opsyonal na cloud sync para sa multi-device/state sync -- IP allowlist/blocklist para sa API access control -- Pag-iisip ng pamamahala sa badyet (passthrough/auto/custom/adaptive) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) - Global system prompt injection -- Pagsubaybay sa session at fingerprinting -- Paglilimita sa pinahusay na rate ng bawat account gamit ang mga profile na partikular sa provider -- Pattern ng circuit breaker para sa katatagan ng provider -- Proteksyon laban sa dumadagundong na kawan na may mutex locking -- Nakabatay sa lagda ang cache ng pag-deduplication ng kahilingan -- Layer ng domain: availability ng modelo, mga panuntunan sa gastos, patakaran sa fallback, patakaran sa lockout -- Pananatili ng estado ng domain (SQLite write-through cache para sa mga fallback, badyet, lockout, circuit breaker) -- Policy engine para sa sentralisadong pagsusuri ng kahilingan (lockout → budget → fallback) -- Humiling ng telemetry na may p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) para sa end-to-end na pagsubaybay -- Pag-log sa audit ng pagsunod gamit ang opt-out sa bawat API key -- Eval framework para sa katiyakan ng kalidad ng LLM -- Resilience UI dashboard na may real-time na status ng circuit breaker -- Modular OAuth providers (12 indibidwal na module sa ilalim ng `src/lib/oauth/providers/`) +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Pangunahing modelo ng runtime: +Primary runtime model: -- Ang mga ruta ng Next.js app sa ilalim ng `src/app/api/*` ay nagpapatupad ng parehong dashboard API at compatibility API -- Isang nakabahaging SSE/routing core sa `src/sse/*` + `open-sse/*` ang humahawak sa pagpapatupad ng provider, pagsasalin, streaming, fallback, at paggamit +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Saklaw at Hangganan +## Scope and Boundaries -### Nasa Saklaw +### In Scope -- Lokal na gateway runtime -- Mga API sa pamamahala ng dashboard -- Pagpapatunay ng provider at pag-refresh ng token -- Humiling ng pagsasalin at SSE streaming -- Lokal na estado + pagtitiyaga sa paggamit -- Opsyonal na cloud sync orchestration +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Wala sa Saklaw +### Out of Scope -- Pagpapatupad ng serbisyo sa cloud sa likod ng `NEXT_PUBLIC_CLOUD_URL` -- Provider SLA/control plane sa labas ng lokal na proseso -- Mga panlabas na CLI binary mismo (Claude CLI, Codex CLI, atbp.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Mataas na Antas na Konteksto ng System +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Mga Pangunahing Bahagi ng Runtime +## Core Runtime Components -## 1) API at Routing Layer (Next.js App Routes) +## 1) API and Routing Layer (Next.js App Routes) -Mga pangunahing direktoryo: +Main directories: -- `src/app/api/v1/*` at `src/app/api/v1beta/*` para sa mga compatibility API -- `src/app/api/*` para sa mga management/configuration API -- Susunod na muling pagsusulat sa `next.config.mjs` mapa `/v1/*` hanggang `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Mahahalagang ruta ng compatibility: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — kasama ang mga custom na modelo na may `custom: true` -- `src/app/api/v1/embeddings/route.ts` — henerasyon ng pag-embed (6 na provider) -- `src/app/api/v1/images/generations/route.ts` — pagbuo ng larawan (4+ provider kasama ang Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — nakatuon sa bawat provider na chat -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — nakalaang mga pag-embed ng bawat provider -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — nakalaang mga larawan ng bawat provider +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Mga domain ng pamamahala: +Management domains: -- Auth/setting: `src/app/api/auth/*`, `src/app/api/settings/*` -- Mga provider/koneksyon: `src/app/api/providers*` -- Mga node ng provider: `src/app/api/provider-nodes*` -- Mga custom na modelo: `src/app/api/provider-models` (GET/POST/DELETE) -- Catalog ng modelo: `src/app/api/models/catalog` (GET) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) - Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Mga key/alias/combos/presyo: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Paggamit: `src/app/api/usage/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` - Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` - CLI tooling helpers: `src/app/api/cli-tools/*` - IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Pag-iisip na badyet: `src/app/api/settings/thinking-budget` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) - System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Mga Sesyon: `src/app/api/sessions` (GET) -- Mga limitasyon sa rate: `src/app/api/rate-limits` (GET) -- Katatagan: `src/app/api/resilience` (GET/PATCH) — mga profile ng provider, circuit breaker, estado ng limitasyon sa rate +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state - Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns -- Mga istatistika ng cache: `src/app/api/cache/stats` (GET/DELETE) -- Availability ng modelo: `src/app/api/models/availability` (GET/POST) +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) - Telemetry: `src/app/api/telemetry/summary` (GET) -- Badyet: `src/app/api/usage/budget` (GET/POST) -- Fallback chain: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Pag-audit sa pagsunod: `src/app/api/compliance/audit-log` (GET) -- Mga Eval: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Mga Patakaran: `src/app/api/policies` (GET/POST) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Core ng Pagsasalin +## 2) SSE + Translation Core -Mga pangunahing module ng daloy: +Main flow modules: - Entry: `src/sse/handlers/chat.ts` - Core orchestration: `open-sse/handlers/chatCore.ts` -- Mga adaptor ng pagpapatupad ng provider: `open-sse/executors/*` +- Provider execution adapters: `open-sse/executors/*` - Format detection/provider config: `open-sse/services/provider.ts` -- Pag-parse/paglutas ng modelo: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Logic ng fallback ng account: `open-sse/services/accountFallback.ts` -- Pagpapatala ng pagsasalin: `open-sse/translator/index.ts` -- Mga pagbabago sa stream: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Pagkuha/normalisasyon ng paggamit: `open-sse/utils/usageTracking.ts` -- Isipin ang tag parser: `open-sse/utils/thinkTagParser.ts` -- Handler ng pag-embed: `open-sse/handlers/embeddings.ts` -- Pag-embed ng pagpapatala ng provider: `open-sse/config/embeddingRegistry.ts` -- Handler ng pagbuo ng larawan: `open-sse/handlers/imageGeneration.ts` -- Rehistro ng provider ng larawan: `open-sse/config/imageRegistry.ts` -- Paglinis ng tugon: `open-sse/handlers/responseSanitizer.ts` -- Pag-normalize ng tungkulin: `open-sse/services/roleNormalizer.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Mga Serbisyo (lohika ng negosyo): +Services (business logic): -- Pagpili/pagmamarka ng account: `open-sse/services/accountSelector.ts` -- Pamamahala ng lifecycle ng konteksto: `open-sse/services/contextManager.ts` -- Pagpapatupad ng IP filter: `open-sse/services/ipFilter.ts` -- Pagsubaybay sa session: `open-sse/services/sessionManager.ts` -- Humiling ng deduplikasyon: `open-sse/services/signatureCache.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` - System prompt injection: `open-sse/services/systemPrompt.ts` -- Pag-iisip ng pamamahala sa badyet: `open-sse/services/thinkingBudget.ts` -- Pagruruta ng modelo ng wildcard: `open-sse/services/wildcardRouter.ts` -- Pamamahala sa limitasyon ng rate: `open-sse/services/rateLimitManager.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` - Circuit breaker: `open-sse/services/circuitBreaker.ts` -Mga module ng layer ng domain: +Domain layer modules: -- Availability ng modelo: `src/lib/domain/modelAvailability.ts` -- Mga panuntunan/badyet ng gastos: `src/lib/domain/costRules.ts` -- Patakaran sa Fallback: `src/lib/domain/fallbackPolicy.ts` -- Combo solver: `src/lib/domain/comboResolver.ts` -- Patakaran sa pag-lockout: `src/lib/domain/lockoutPolicy.ts` -- Policy engine: `src/domain/policyEngine.ts` — sentralisadong lockout → badyet → fallback evaluation -- Catalog ng mga error code: `src/lib/domain/errorCodes.ts` +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` - Request ID: `src/lib/domain/requestId.ts` -- I-fetch ang timeout: `src/lib/domain/fetchTimeout.ts` -- Humiling ng telemetry: `src/lib/domain/requestTelemetry.ts` -- Pagsunod/pag-audit: `src/lib/domain/compliance/index.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` - Eval runner: `src/lib/domain/evalRunner.ts` -- Pananatili ng estado ng domain: `src/lib/db/domainState.ts` — SQLite CRUD para sa mga fallback na chain, badyet, kasaysayan ng gastos, estado ng lockout, mga circuit breaker +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Mga module ng provider ng OAuth (12 indibidwal na file sa ilalim ng `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): - Registry index: `src/lib/oauth/providers/index.ts` -- Mga indibidwal na tagapagbigay: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Manipis na wrapper: `src/lib/oauth/providers.ts` — muling pag-export mula sa mga indibidwal na module +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Layer ng Pagtitiyaga +## 3) Persistence Layer -Pangunahing estado DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- file: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` kapag nakatakda, kung hindi `~/.omniroute/db.json`) -- mga entity: providerConnections, providerNodes, modelAliases, combos, apiKeys, mga setting, pagpepresyo, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Paggamit ng DB: +Usage persistence: -- `src/lib/usageDb.ts` -- mga file: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- sumusunod sa parehong base na patakaran sa direktoryo gaya ng `localDb` (`DATA_DIR`, pagkatapos ay `XDG_CONFIG_HOME/omniroute` kapag nakatakda) -- nabulok sa mga nakatutok na sub-modules: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — CRUD operations para sa domain state -- Mga talahanayan (ginawa sa `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Write-through na cache pattern: in-memoryang Maps ay may awtoridad sa runtime; ang mga mutasyon ay nakasulat nang sabay-sabay sa SQLite; ang estado ay naibalik mula sa DB sa malamig na simula +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start ## 4) Auth + Security Surfaces - Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Pagbuo/pag-verify ng API key: `src/shared/utils/apiKey.ts` -- Nagpatuloy ang mga lihim ng provider sa `providerConnections` na mga entry -- Outbound proxy na suporta sa pamamagitan ng `open-sse/utils/proxyFetch.ts` (env vars) at `open-sse/utils/networkProxy.ts` (nako-configure sa bawat provider o global) +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) ## 5) Cloud Sync - Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Pana-panahong gawain: `src/shared/services/cloudSyncScheduler.ts` -- Ruta ng kontrol: `src/app/api/sync/cloud/route.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Humiling ng Lifecycle (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Daloy ng Fallback ng Account +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Ang mga desisyon sa pagbabalik ay hinihimok ng `open-sse/services/accountFallback.ts` gamit ang mga status code at heuristic ng error-message. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth Onboarding at Token Refresh Lifecycle +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Ang pag-refresh sa panahon ng live na trapiko ay isinasagawa sa loob ng `open-sse/handlers/chatCore.ts` sa pamamagitan ng executor na `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Lifecycle ng Cloud Sync (Paganahin / Pag-sync / I-disable) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Ang pana-panahong pag-sync ay na-trigger ng `CloudSyncScheduler` kapag pinagana ang cloud. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Modelo ng Data at Imbakan ng Mapa +## Data Model and Storage Map ```mermaid erDiagram @@ -503,12 +504,12 @@ erDiagram } ``` -Mga file ng pisikal na storage: +Physical storage files: -- pangunahing estado: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` kapag nakatakda, kung hindi `~/.omniroute/db.json`) -- mga istatistika ng paggamit: `${DATA_DIR}/usage.json` -- humiling ng mga linya ng log: `${DATA_DIR}/log.txt` -- opsyonal na tagasalin/paghiling ng mga sesyon ng pag-debug: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` ## Deployment Topology @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Module Mapping (Desisyon-Kritikal) +## Module Mapping (Decision-Critical) -### Mga Module ng Ruta at API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: mga compatibility API -- `src/app/api/v1/providers/[provider]/*`: nakalaang mga ruta ng bawat provider (chat, mga pag-embed, mga larawan) -- `src/app/api/providers*`: provider CRUD, pagpapatunay, pagsubok -- `src/app/api/provider-nodes*`: custom na katugmang pamamahala ng node -- `src/app/api/provider-models`: pamamahala ng custom na modelo (CRUD) -- `src/app/api/models/catalog`: full model catalog API (lahat ng uri ay nakapangkat ayon sa provider) -- `src/app/api/oauth/*`: Mga daloy ng OAuth/device-code -- `src/app/api/keys*`: lokal na API key lifecycle -- `src/app/api/models/alias`: pamamahala ng alias +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management - `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: na-override ang pagpepresyo para sa pagkalkula ng gastos +- `src/app/api/pricing`: pricing overrides for cost calculation - `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) - `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: mga API sa paggamit at mga log -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync at cloud-facing helper -- `src/app/api/cli-tools/*`: mga lokal na CLI config writers/checkers +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers - `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) - `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) - `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: aktibong listahan ng session (GET) +- `src/app/api/sessions`: active session listing (GET) - `src/app/api/rate-limits`: per-account rate limit status (GET) -### Routing at Execution Core +### Routing and Execution Core - `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: pagsasalin, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: network na partikular sa provider at gawi sa format +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Translation Registry at Format Converters +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: rehistro ng tagasalin at orkestrasyon -- Humiling ng mga tagasalin: `open-sse/translator/request/*` -- Mga tagasalin ng tugon: `open-sse/translator/response/*` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` - Format constants: `open-sse/translator/formats.ts` -### Pagtitiyaga +### Persistence -- `src/lib/localDb.ts`: paulit-ulit na config/state -- `src/lib/usageDb.ts`: history ng paggamit at rolling request logs +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Saklaw ng Tagapagpatupad ng Provider (Pattern ng Diskarte) +## Provider Executor Coverage (Strategy Pattern) -Ang bawat provider ay may dalubhasang tagapagpatupad na nagpapalawak ng `BaseExecutor` (sa `open-sse/executors/base.ts`), na nagbibigay ng pagbuo ng URL, pagbuo ng header, muling subukang may exponential backoff, mga credential refresh hook, at ang `execute()` na paraan ng orkestrasyon. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Tagapagpatupad | (Mga) Provider | Espesyal na Paghawak | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic na URL/header config bawat provider | -| `AntigravityExecutor` | Google Antigravity | Mga custom na project/session ID, Retry-After parsing | -| `CodexExecutor` | OpenAI Codex | Nag-inject ng mga tagubilin sa system, pinipilit ang pagsisikap sa pangangatwiran | -| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, kahilingan sa pagpirma sa pamamagitan ng checksum | -| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking header | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | -| `GeminiCLIExecutor` | Gemini CLI | Ikot ng pag-refresh ng token ng Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Ang lahat ng iba pang provider (kabilang ang mga custom na katugmang node) ay gumagamit ng `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. ## Provider Compatibility Matrix -| Provider | Format | Awth | Stream | Hindi Stream | Pag-refresh ng Token | Paggamit ng API | -| ---------------- | ---------------- | --------------------- | ---------------- | ------------ | -------------------- | ----------------------------- | -| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin lang | -| Gemini | Gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Gemini CLI | Gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Buong quota API | -| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-responses | OAuth | ✅ pinilit | ❌ | ✅ | ✅ Mga limitasyon sa rate | -| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Mga snapshot ng quota | -| Cursor | cursor | Custom na checksum | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Mga limitasyon sa paggamit | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Bawat kahilingan | -| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Bawat kahilingan | -| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Pagkagulo | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Magkasama AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Sakop ng Pagsasalin ng Format +## Format Translation Coverage -Kasama sa mga natukoy na format ng pinagmulan ang: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Kasama sa mga target na format ang: +Target formats include: -- OpenAI chat/Mga Tugon +- OpenAI chat/Responses - Claude - Gemini/Gemini-CLI/Antigravity envelope - Kiro - Cursor -Ginagamit ng mga pagsasalin ang **OpenAI bilang hub format** — lahat ng conversion ay dumadaan sa OpenAI bilang intermediate: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Pinipili ang mga pagsasalin sa dynamic na paraan batay sa hugis ng source payload at format ng target ng provider. +Translations are selected dynamically based on source payload shape and provider target format. -Mga karagdagang layer ng pagpoproseso sa pipeline ng pagsasalin: +Additional processing layers in the translation pipeline: -- **Response sanitization** — Tinatanggal ang mga hindi karaniwang field mula sa OpenAI-format na mga tugon (parehong streaming at non-streaming) para matiyak ang mahigpit na pagsunod sa SDK -- **Pag-normalize ng tungkulin** — Kino-convert ang `developer` → `system` para sa mga target na hindi OpenAI; pinagsasama ang `system` → `user` para sa mga modelong tumatanggi sa papel ng system (GLM, ERNIE) -- **Isipin ang pagkuha ng tag** — Pina-parse ang `...` na mga bloke mula sa nilalaman patungo sa `reasoning_content` na field -- **Structured output** — Kino-convert ang OpenAI `response_format.json_schema` sa Gemini's `responseMimeType` + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Mga Sinusuportahang API Endpoints +## Supported API Endpoints -| Endpoint | Format | Handler | -| -------------------------------------------------- | ------------------------- | --------------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Messages | Parehong handler (auto-detected) | -| `POST /v1/responses` | Mga Tugon sa OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Listahan ng modelo | ruta ng API | -| `POST /v1/images/generations` | Mga Larawan ng OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Listahan ng modelo | ruta ng API | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Nakatuon sa bawat provider na may pagpapatunay ng modelo | -| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Nakatuon sa bawat provider na may pagpapatunay ng modelo | -| `POST /v1/providers/{provider}/images/generations` | Mga Larawan ng OpenAI | Nakatuon sa bawat provider na may pagpapatunay ng modelo | -| `POST /v1/messages/count_tokens` | Bilang ng Token ng Claude | ruta ng API | -| `GET /v1/models` | Listahan ng OpenAI Models | ruta ng API (chat + pag-embed + larawan + mga custom na modelo) | -| `GET /api/models/catalog` | Catalog | Lahat ng mga modelo ay nakapangkat ayon sa provider + uri | -| `POST /v1beta/models/*:streamGenerateContent` | Taong Gemini | ruta ng API | -| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Configuration ng proxy ng network | -| `POST /api/settings/proxy/test` | Pagkakakonekta ng Proxy | Endpoint ng pagsubok sa kalusugan/pagkakakonekta ng proxy | -| `GET/POST/DELETE /api/provider-models` | Mga Custom na Modelo | Pamamahala ng custom na modelo sa bawat provider | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | ## Bypass Handler -Hinaharang ng bypass handler (`open-sse/utils/bypassHandler.ts`) ang mga kilalang "throwaway" na kahilingan mula kay Claude CLI — mga warmup ping, pagkuha ng pamagat, at bilang ng token — at nagbabalik ng **pekeng tugon** nang hindi gumagamit ng upstream na mga token ng provider. Nati-trigger lang ito kapag ang `User-Agent` ay naglalaman ng `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Humiling ng Logger Pipeline +## Request Logger Pipeline -Ang request logger (`open-sse/utils/requestLogger.ts`) ay nagbibigay ng 7-stage na debug logging pipeline, na hindi pinagana bilang default, na pinagana sa pamamagitan ng `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Ang mga file ay isinulat sa `/logs//` para sa bawat sesyon ng kahilingan. +Files are written to `/logs//` for each request session. -## Mga Mode ng Pagkabigo at Katatagan +## Failure Modes and Resilience -## 1) Availability ng Account/Provider +## 1) Account/Provider Availability -- cooldown ng provider account sa mga lumilipas/rate/auth error -- fallback ng account bago mabigo ang kahilingan -- fallback ng combo model kapag naubos na ang kasalukuyang modelo/provider path +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Pag-expire ng Token +## 2) Token Expiry -- paunang suriin at i-refresh na may muling pagsubok para sa mga nare-refresh na provider -- 401/403 subukang muli pagkatapos ng pagtatangka sa pag-refresh sa pangunahing landas +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Kaligtasan ng Stream +## 3) Stream Safety - disconnect-aware stream controller -- translation stream na may end-of-stream flush at `[DONE]` handling -- fallback sa pagtatantya ng paggamit kapag nawawala ang metadata ng paggamit ng provider +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Pagbaba ng Cloud Sync +## 4) Cloud Sync Degradation -- Lumilitaw ang mga error sa pag-sync ngunit nagpapatuloy ang lokal na runtime -- Ang scheduler ay may retry-capable logic, ngunit ang pana-panahong execution ay kasalukuyang tumatawag sa single-attempt sync bilang default +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integridad ng Data +## 5) Data Integrity -- Paglipat/pagkumpuni ng hugis ng DB para sa mga nawawalang key -- tiwaling JSON reset safeguards para sa localDb at usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Pagmamasid at Mga Signal ng Operasyon +## Observability and Operational Signals -Runtime visibility source: +Runtime visibility sources: -- mga console log mula sa `src/sse/utils/logger.ts` -- mga pinagsama-samang paggamit sa bawat kahilingan sa `usage.json` -- log in sa status ng text na kahilingan `log.txt` -- opsyonal na malalim na kahilingan/mga log ng pagsasalin sa ilalim ng `logs/` kapag `ENABLE_REQUEST_LOGS=true` -- mga endpoint sa paggamit ng dashboard (`/api/usage/*`) para sa paggamit ng UI +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Mga Hangganan na Sensitibo sa Seguridad +## Security-Sensitive Boundaries -- Sikreto ng JWT (`JWT_SECRET`) ay sinisiguro ang pag-verify/pagpirma ng cookie ng session ng dashboard -- Dapat na ma-override ang paunang password (`INITIAL_PASSWORD`, default na `123456`) sa mga totoong deployment -- Ang API key HMAC secret (`API_KEY_SECRET`) ay sinisiguro ang nabuong lokal na format ng API key -- Ang mga lihim ng provider (mga API key/token) ay nananatili sa lokal na DB at dapat na protektahan sa antas ng filesystem -- Umaasa ang mga endpoint ng cloud sync sa API key auth + semantics ng machine id +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Environment at Runtime Matrix +## Environment and Runtime Matrix -Mga variable ng kapaligiran na aktibong ginagamit ng code: +Environment variables actively used by code: - App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` -- Imbakan: `DATA_DIR` -- Katugmang pag-uugali ng node: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Opsyonal na storage base override (Linux/macOS kapag `DATA_DIR` unset): `XDG_CONFIG_HOME` -- Hashing ng seguridad: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Pag-log: `ENABLE_REQUEST_LOGS` -- Pag-sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Papalabas na proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` at lowercase na mga variant -- Mga flag ng tampok na SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Mga katulong sa platform/runtime (hindi config na partikular sa app): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Mga Kilalang Architectural Notes +## Known Architectural Notes -1. Ibinabahagi na ngayon ng `usageDb` at `localDb` ang parehong base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) na may legacy na paglipat ng file. -2. Nagbabalik ang `/api/v1/route.ts` ng static na listahan ng modelo at hindi ito ang pangunahing pinagmumulan ng mga modelo na ginagamit ng `/v1/models`. -3. Ang Request logger ay nagsusulat ng buong header/body kapag pinagana; ituring ang direktoryo ng log bilang sensitibo. -4. Ang pag-uugali ng cloud ay nakasalalay sa tamang `NEXT_PUBLIC_BASE_URL` at maabot ang endpoint ng cloud. -5. Ang `open-sse/` na direktoryo ay na-publish bilang ang `@omniroute/open-sse` **npm workspace package**. Ini-import ito ng source code sa pamamagitan ng `@omniroute/open-sse/...` (nalutas ng Next.js `transpilePackages`). Ginagamit pa rin ng mga file path sa dokumentong ito ang pangalan ng direktoryo na `open-sse/` para sa pagkakapare-pareho. -6. Ang mga chart sa dashboard ay gumagamit ng **Recharts** (SVG-based) para sa naa-access, interactive na mga visualization ng analytics (mga bar chart ng paggamit ng modelo, mga talahanayan ng breakdown ng provider na may mga rate ng tagumpay). -7. Ang mga pagsusulit sa E2E ay gumagamit ng **Playwright** (`tests/e2e/`), tumatakbo sa pamamagitan ng `npm run test:e2e`. Gumagamit ang mga unit test ng **Node.js test runner** (`tests/unit/`), na tumatakbo sa pamamagitan ng `npm run test:plan3`. Ang source code sa ilalim ng `src/` ay **TypeScript** (`.ts`/`.tsx`); ang `open-sse/` workspace ay nananatiling JavaScript (`.js`). -8. Ang pahina ng mga setting ay isinaayos sa 5 tab: Seguridad, Pagruruta (6 na pandaigdigang diskarte: fill-first, round-robin, p2c, random, hindi gaanong ginagamit, cost-optimized), Resilience (editable rate limits, circuit breaker, mga patakaran), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Checklist ng Pagpapatunay ng Operasyon +## Operational Verification Checklist -- Bumuo mula sa pinagmulan: `npm run build` -- Bumuo ng larawan ng Docker: `docker build -t omniroute .` -- Simulan ang serbisyo at i-verify: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- Ang CLI target base URL ay dapat na `http://:20128/v1` kapag `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/phi/CODEBASE_DOCUMENTATION.md b/docs/i18n/phi/CODEBASE_DOCUMENTATION.md index dd31712039..303880c198 100644 --- a/docs/i18n/phi/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/phi/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ # omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Isang komprehensibo, madaling gabay sa baguhan sa **omniroute** multi-provider AI proxy router. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Ano ang omniroute? +## 1. What Is omniroute? -Ang omniroute ay isang **proxy router** na nasa pagitan ng mga kliyente ng AI (Claude CLI, Codex, Cursor IDE, atbp.) at mga tagapagbigay ng AI (Anthropic, Google, OpenAI, AWS, GitHub, atbp.). Malulutas nito ang isang malaking problema: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Ang iba't ibang mga kliyente ng AI ay nagsasalita ng iba't ibang "mga wika" (mga format ng API), at ang iba't ibang mga tagapagbigay ng AI ay umaasa din ng iba't ibang "mga wika."** Ang omniroute ay awtomatikong nagsasalin sa pagitan ng mga ito. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Isipin ito na parang isang unibersal na tagasalin sa United Nations — sinumang delegado ay maaaring magsalita ng anumang wika, at ang tagasalin ay nagko-convert nito para sa sinumang ibang delegado. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Pangkalahatang-ideya ng Arkitektura +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Pangunahing Prinsipyo: Hub-and-Spoke Translation +### Core Principle: Hub-and-Spoke Translation -Ang lahat ng pagsasalin ng format ay dumadaan sa **OpenAI na format bilang hub**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Nangangahulugan ito na kailangan mo lang ng **N na tagasalin** (isa bawat format) sa halip na **N²** (bawat pares). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Istruktura ng Proyekto +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Pagkakabahagi ng Module-by-Module +## 4. Module-by-Module Breakdown ### 4.1 Config (`open-sse/config/`) -Ang **nag-iisang pinagmulan ng katotohanan** para sa lahat ng configuration ng provider. +The **single source of truth** for all provider configuration. -| File | Layunin | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` object na may mga base URL, mga kredensyal ng OAuth (mga default), header, at default na prompt ng system para sa bawat provider. Tinutukoy din ang `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, at `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Naglo-load ng mga panlabas na kredensyal mula sa `data/provider-credentials.json` at pinagsasama ang mga ito sa mga naka-hardcode na default sa `PROVIDERS`. Pinapanatili ang mga lihim na wala sa kontrol ng pinagmulan habang pinapanatili ang pabalik na pagkakatugma. | -| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Mga function tulad ng `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Mga tagubilin ng system na ini-inject sa mga kahilingan sa Codex (mga hadlang sa pag-edit, mga panuntunan sa sandbox, mga patakaran sa pag-apruba). | -| `defaultThinkingSignature.ts` | Default na "pag-iisip" na mga lagda para sa mga modelong Claude at Gemini. | -| `ollamaModels.ts` | Depinisyon ng schema para sa mga lokal na modelo ng Ollama (pangalan, laki, pamilya, quantization). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Daloy ng Paglo-load ng Kredensyal +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Mga Tagapagpatupad (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Inilalagay ng mga tagapagpatupad ang **lohika na tukoy sa provider** gamit ang **Pattern ng Diskarte**. Ino-override ng bawat executor ang mga base method kung kinakailangan. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Tagapagpatupad | Provider | Mga Pangunahing Espesyalisasyon | -| ---------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Abstract base: Pagbuo ng URL, mga header, subukang muli ang logic, pag-refresh ng kredensyal | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic na OAuth token refresh para sa mga karaniwang provider | -| `antigravity.ts` | Google Cloud Code | Pagbuo ng Project/session ID, multi-URL fallback, custom na muling subukang pag-parse mula sa mga mensahe ng error ("i-reset pagkatapos ng 2h7m23s") | -| `cursor.ts` | Cursor IDE | **Pinakakumplikado**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | -| `codex.ts` | OpenAI Codex | Nag-inject ng mga tagubilin sa system, namamahala sa mga antas ng pag-iisip, nag-aalis ng mga hindi sinusuportahang parameter | -| `gemini-cli.ts` | Google Gemini CLI | Pagbuo ng custom na URL (`streamGenerateContent`), pag-refresh ng token ng Google OAuth | -| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), paggaya ng header ng VSCode | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | -| `index.ts` | — | Pabrika: maps provider name → executor class, na may default na fallback | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Mga Handler (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -Ang **orchestration layer** — nag-coordinate ng pagsasalin, execution, streaming, at paghawak ng error. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| File | Layunin | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Central orchestrator** (~600 linya). Pinangangasiwaan ang kumpletong lifecycle ng kahilingan: pagtukoy ng format → pagsasalin → dispatch ng tagapagpatupad → tugon sa streaming/hindi streaming → pag-refresh ng token → paghawak ng error → pag-log sa paggamit. | -| `responsesHandler.ts` | Adapter para sa OpenAI's Responses API: kino-convert ang format ng Mga Tugon → Mga Pagkumpleto ng Chat → ipinapadala sa `chatCore` → ibinalik ang SSE sa format ng Mga Tugon. | -| `embeddings.ts` | Tagapangasiwa ng henerasyon ng pag-embed: niresolba ang modelo ng pag-embed → provider, nagpapadala sa API ng provider, nagbabalik ng tugon sa pag-embed na katugma sa OpenAI. Sinusuportahan ang 6+ provider. | -| `imageGeneration.ts` | Handler ng pagbuo ng imahe: niresolba ang modelo ng imahe → provider, sumusuporta sa OpenAI-compatible, Gemini-image (Antigravity), at fallback (Nebius) mode. Ibinabalik ang base64 o mga larawan ng URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Humiling ng Lifecycle (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,26 +258,26 @@ sequenceDiagram --- -### 4.4 Mga Serbisyo (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Logic ng negosyo na sumusuporta sa mga humahawak at tagapagpatupad. +Business logic that supports the handlers and executors. -| File | Layunin | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Format detection** (`detectFormat`): sinusuri ang request body structure para matukoy ang mga format ng Claude/OpenAI/Gemini/Antigravity/Responses (kasama ang `max_tokens` heuristic para kay Claude). Gayundin: pagbuo ng URL, pagbuo ng header, pag-normalize ng config ng pag-iisip. Sinusuportahan ang `openai-compatible-*` at `anthropic-compatible-*` na mga dynamic na provider. | -| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution na may collision detection, input sanitization (tinatanggihan ang path traversal/control chars), at resolution ng impormasyon ng modelo na may suporta sa async alias getter. | -| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), pamamahala ng cooldown ng account, pag-uuri ng error (na ang mga error ay nagti-trigger ng fallback vs. not). | -| `tokenRefresh.ts` | OAuth token refresh para sa **bawat provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). May kasamang in-flight promise deduplication cache at subukang muli nang may exponential backoff. | -| `combo.ts` | **Mga modelong combo**: mga chain ng fallback na modelo. Kung nabigo ang modelong A na may error na karapat-dapat sa fallback, subukan ang modelo B, pagkatapos ay C, atbp. Ibinabalik ang mga aktwal na upstream na status code. | -| `usage.ts` | Kinukuha ang quota/data ng paggamit mula sa mga provider API (GitHub Copilot quota, Antigravity model quota, Codex rate limits, Kiro usage breakdowns, Claude settings). | -| `accountSelector.ts` | Pagpili ng matalinong account na may algorithm ng pagmamarka: isinasaalang-alang ang priyoridad, katayuan sa kalusugan, posisyon ng round-robin, at estado ng cooldown upang piliin ang pinakamainam na account para sa bawat kahilingan. | -| `contextManager.ts` | Humiling ng pamamahala sa lifecycle ng konteksto: gumagawa at sumusubaybay ng mga object ng konteksto sa bawat kahilingan na may metadata (request ID, timestamp, impormasyon ng provider) para sa pag-debug at pag-log. | -| `ipFilter.ts` | IP-based na access control: sumusuporta sa allowlist at blocklist mode. Pinapatunayan ang IP ng kliyente laban sa mga na-configure na panuntunan bago iproseso ang mga kahilingan sa API. | -| `sessionManager.ts` | Pagsubaybay sa session gamit ang fingerprinting ng kliyente: sinusubaybayan ang mga aktibong session gamit ang mga na-hash na identifier ng kliyente, sinusubaybayan ang mga bilang ng kahilingan, at nagbibigay ng mga sukatan ng session. | -| `signatureCache.ts` | Humiling ng signature-based na deduplication cache: pinipigilan ang mga duplicate na kahilingan sa pamamagitan ng pag-cache ng mga kamakailang pirma ng kahilingan at pagbabalik ng mga naka-cache na tugon para sa magkaparehong mga kahilingan sa loob ng isang palugit ng oras. | -| `systemPrompt.ts` | Global system prompt injection: naghahanda o nagdaragdag ng isang nako-configure na prompt ng system sa lahat ng kahilingan, na may paghawak sa compatibility ng bawat provider. | -| `thinkingBudget.ts` | Pamamahala ng badyet ng token ng pangangatwiran: sumusuporta sa passthrough, auto (strip thinking config), custom (fixed budget), at adaptive (complexity-scaled) na mga mode para sa pagkontrol sa mga token ng pag-iisip/pangangatwiran. | -| `wildcardRouter.ts` | Pagruruta ng pattern ng wildcard na modelo: nire-resolba ang mga pattern ng wildcard (hal., `*/claude-*`) sa mga kongkretong pares ng provider/modelo batay sa availability at priyoridad. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | #### Token Refresh Deduplication @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Tagasalin (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -Ang **format translation engine** gamit ang isang self-registering plugin system. +The **format translation engine** using a self-registering plugin system. -#### Arkitektura +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Direktoryo | Mga file | Paglalarawan | -| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 tagasalin | I-convert ang mga katawan ng kahilingan sa pagitan ng mga format. Ang bawat file ay nagrerehistro sa pamamagitan ng `register(from, to, fn)` sa pag-import. | -| `response/` | 7 tagasalin | I-convert ang mga tipak ng tugon sa streaming sa pagitan ng mga format. Pinangangasiwaan ang mga uri ng kaganapan sa SSE, mga bloke ng pag-iisip, mga tawag sa tool. | -| `helpers/` | 6 na katulong | Mga nakabahaging utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/content mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `toolCallHelper`, `toolCallHelper`8 | -| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, pamamahala ng estado, pagpapatala. | -| `formats.ts` | — | Mga constant ng format: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Pangunahing Disenyo: Self-Registering Plugin +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,17 +395,17 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Mga Util (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| File | Layunin | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction mula sa mga error message, SSE error streaming. | -| `stream.ts` | **SSE Transform Stream** — ang pangunahing streaming pipeline. Dalawang mode: `TRANSLATE` (buong format na pagsasalin) at `PASSTHROUGH` (normalize + paggamit ng extract). Pinangangasiwaan ang chunk buffering, pagtatantya ng paggamit, pagsubaybay sa haba ng nilalaman. Ang mga instance ng per-stream encoder/decoder ay umiiwas sa nakabahaging estado. | -| `streamHelpers.ts` | Mga mababang antas ng SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filter ang mga walang laman na chunks para sa OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware na SSE_0K na serialization na may ). | -| `usageTracking.ts` | Pagkuha ng paggamit ng token mula sa anumang format (Claude/OpenAI/Gemini/Responses), pagtatantya na may hiwalay na tool/message char-per-token ratios, pagdaragdag ng buffer (2000 token safety margin), pag-filter ng field na partikular sa format, console logging na may mga kulay ng ANSI. | -| `requestLogger.ts` | Nakabatay sa file ang pag-log ng kahilingan (opt-in sa pamamagitan ng `ENABLE_REQUEST_LOGS=true`). Lumilikha ng mga folder ng session na may mga file na may numero: `1_req_client.json` → `7_res_client.txt`. Ang lahat ng I/O ay async (fire-and-forget). Maskara ang mga sensitibong header. | -| `bypassHandler.ts` | Hinaharang ang mga partikular na pattern mula kay Claude CLI (pagkuha ng pamagat, warmup, count) at ibinabalik ang mga pekeng tugon nang hindi tumatawag sa sinumang provider. Sinusuportahan ang parehong streaming at hindi streaming. Sinadyang limitado sa saklaw ng Claude CLI. | -| `networkProxy.ts` | Nire-resolve ang outbound proxy URL para sa isang ibinigay na provider nang nangunguna: provider-specific config → global config → environment variable (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Sinusuportahan ang `NO_PROXY` na mga pagbubukod. Caches config para sa 30s. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | #### SSE Streaming Pipeline @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Istraktura ng Session ng Logger ng Kahilingan +#### Request Logger Session Structure ``` logs/ @@ -449,107 +449,107 @@ logs/ ### 4.7 Application Layer (`src/`) -| Direktoryo | Layunin | -| ------------- | -------------------------------------------------------------------------------- | -| `src/app/` | Web UI, mga ruta ng API, Express middleware, OAuth callback handler | -| `src/lib/` | Access sa database (`localDb.ts`, `usageDb.ts`), pagpapatunay, ibinahagi | -| `src/mitm/` | Man-in-the-middle proxy utility para sa pagharang sa trapiko ng provider | -| `src/models/` | Mga kahulugan ng modelo ng database | -| `src/shared/` | Mga wrapper sa paligid ng mga open-sse function (provider, stream, error, atbp.) | -| `src/sse/` | SSE endpoint handler na nag-wire ng open-sse library sa Express na mga ruta | -| `src/store/` | Pamamahala ng estado ng aplikasyon | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Kapansin-pansing Mga Ruta ng API +#### Notable API Routes -| Ruta | Mga Paraan | Layunin | -| --------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | GET/POST/DELETE | CRUD para sa mga custom na modelo sa bawat provider | -| `/api/models/catalog` | KUMUHA | Pinagsama-samang catalog ng lahat ng modelo (chat, pag-embed, larawan, custom) na nakapangkat ayon sa provider | -| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Pinapatunayan ang koneksyon ng proxy at ibinabalik ang pampublikong IP/latency | -| `/v1/providers/[provider]/chat/completions` | POST | Nakatuon sa bawat provider na mga pagkumpleto ng chat na may pagpapatunay ng modelo | -| `/v1/providers/[provider]/embeddings` | POST | Mga nakalaang pag-embed ng bawat provider na may pagpapatunay ng modelo | -| `/v1/providers/[provider]/images/generations` | POST | Nakatuon sa pagbuo ng larawan ng bawat provider na may pagpapatunay ng modelo | -| `/api/settings/ip-filter` | GET/PUT | Pamamahala ng IP allowlist/blocklist | -| `/api/settings/thinking-budget` | GET/PUT | Reasoning token configuration ng badyet (passthrough/auto/custom/adaptive) | -| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection para sa lahat ng kahilingan | -| `/api/sessions` | KUMUHA | Aktibong pagsubaybay sa session at mga sukatan | -| `/api/rate-limits` | KUMUHA | Katayuan ng limitasyon sa rate ng bawat account | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Mga Pangunahing Pattern ng Disenyo +## 5. Key Design Patterns ### 5.1 Hub-and-Spoke Translation -Ang lahat ng mga format ay isinasalin sa pamamagitan ng **OpenAI format bilang hub**. Ang pagdaragdag ng bagong provider ay nangangailangan lamang ng pagsulat ng **isang pares** ng mga tagasalin (sa/mula sa OpenAI), hindi N pares. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Pattern ng Estratehiya ng Tagapatupad +### 5.2 Executor Strategy Pattern -Ang bawat provider ay may nakalaang executor class na nagmana mula sa `BaseExecutor`. Pinipili ng factory sa `executors/index.ts` ang tama sa runtime. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. ### 5.3 Self-Registering Plugin System -Ang mga module ng tagasalin ay nagrerehistro sa kanilang sarili sa pag-import sa pamamagitan ng `register()`. Ang pagdaragdag ng bagong tagasalin ay paggawa lamang ng file at pag-import nito. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Account Fallback na may Exponential Backoff +### 5.4 Account Fallback with Exponential Backoff -Kapag nagbalik ang isang provider ng 429/401/500, maaaring lumipat ang system sa susunod na account, na naglalapat ng mga exponential cooldown (1s → 2s → 4s → max 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Combo Model Chain +### 5.5 Combo Model Chains -Ang isang "combo" ay nagpapangkat ng maraming `provider/model` string. Kung nabigo ang una, awtomatikong mag-fallback sa susunod. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. ### 5.6 Stateful Streaming Translation -Ang pagsasalin ng tugon ay nagpapanatili ng estado sa mga bahagi ng SSE (pagsubaybay sa bloke ng pag-iisip, pag-iipon ng tawag sa tool, pag-index ng block ng nilalaman) sa pamamagitan ng mekanismong `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Buffer sa Kaligtasan sa Paggamit +### 5.7 Usage Safety Buffer -Ang isang 2000-token buffer ay idinagdag sa iniulat na paggamit upang maiwasan ang mga kliyente na maabot ang mga limitasyon sa window ng konteksto dahil sa overhead mula sa mga prompt ng system at pagsasalin ng format. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Mga Sinusuportahang Format +## 6. Supported Formats -| Format | Direksyon | Identifier | -| ------------------------------ | ------------------- | ------------------ | -| Mga Pagkumpleto ng OpenAI Chat | pinagmulan + target | `openai` | -| OpenAI Responses API | pinagmulan + target | `openai-responses` | -| Anthropic Claude | pinagmulan + target | `claude` | -| Google Gemini | pinagmulan + target | `gemini` | -| Google Gemini CLI | target lang | `gemini-cli` | -| Antigravity | pinagmulan + target | `antigravity` | -| AWS Kiro | target lang | `kiro` | -| Cursor | target lang | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Mga Sinusuportahang Provider +## 7. Supported Providers -| Provider | Paraan ng Pagpapatunay | Tagapagpatupad | Pangunahing Tala | -| ------------------------ | ---------------------- | -------------- | -------------------------------------------------------------- | -| Anthropic Claude | API key o OAuth | Default | Gumagamit ng `x-api-key` header | -| Google Gemini | API key o OAuth | Default | Gumagamit ng `x-goog-api-key` header | -| Google Gemini CLI | OAuth | GeminiCLI | Gumagamit ng `streamGenerateContent` endpoint | -| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom na muling subukang pag-parse | -| OpenAI | API key | Default | Standard Bearer auth | -| Codex | OAuth | Codex | Nag-inject ng mga tagubilin sa system, namamahala sa pag-iisip | -| GitHub Copilot | OAuth + Copilot token | Github | Dual token, paggaya ng header ng VSCode | -| Kiro (AWS) | AWS SSO OIDC o Social | Kiro | Binary EventStream pag-parse | -| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | -| Qwen | OAuth | Default | Karaniwang pagpapatunay | -| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | -| OpenRouter | API key | Default | Standard Bearer auth | -| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, gumamit ng `x-api-key` | -| `openai-compatible-*` | API key | Default | Dynamic: anumang endpoint na katugma sa OpenAI | -| `anthropic-compatible-*` | API key | Default | Dynamic: anumang endpoint na katugma sa Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Buod ng Daloy ng Data +## 8. Data Flow Summary -### Kahilingan sa Pag-stream +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Kahilingan na Hindi Nag-stream +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Daloy ng Bypass (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/phi/FEATURES.md b/docs/i18n/phi/FEATURES.md index 54f411ea0e..82cc73b67b 100644 --- a/docs/i18n/phi/FEATURES.md +++ b/docs/i18n/phi/FEATURES.md @@ -1,22 +1,22 @@ # OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Visual na gabay sa bawat seksyon ng OmniRoute dashboard. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Mga Provider +## 🔌 Providers -Pamahalaan ang mga koneksyon sa AI provider: OAuth provider (Claude Code, Codex, Gemini CLI), API key provider (Groq, DeepSeek, OpenRouter), at libreng provider (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Mga combo +## 🎨 Combos -Gumawa ng mga combo sa pagruruta ng modelo na may 6 na diskarte: fill-first, round-robin, power-of-two-choices, random, hindi gaanong ginagamit, at cost-optimized. Ang bawat combo ay nagkakadena ng maraming modelo na may awtomatikong fallback. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) @@ -24,7 +24,7 @@ Gumawa ng mga combo sa pagruruta ng modelo na may 6 na diskarte: fill-first, rou ## 📊 Analytics -Komprehensibong analytics ng paggamit na may pagkonsumo ng token, mga pagtatantya sa gastos, mga heatmap ng aktibidad, lingguhang chart ng pamamahagi, at mga breakdown sa bawat provider. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) @@ -32,23 +32,42 @@ Komprehensibong analytics ng paggamit na may pagkonsumo ng token, mga pagtatanty ## 🏥 System Health -Real-time na pagsubaybay: uptime, memorya, bersyon, latency percentiles (p50/p95/p99), mga istatistika ng cache, at mga estado ng circuit breaker ng provider. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Palaruan ng Tagasalin +## 🔧 Translator Playground -Apat na mode para sa pag-debug ng mga pagsasalin ng API: **Playground** (format converter), **Chat Tester** (live na kahilingan), **Test Bench** (batch tests), at **Live Monitor** (real-time stream). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Mga Setting +## 🎮 Model Playground _(v2.0.9+)_ -Mga pangkalahatang setting, system storage, backup management (export/import database), hitsura (dark/light mode), seguridad (kasama ang API endpoint protection at custom provider blocking), routing (model aliases, background task degradation), resilience, at advanced configuration. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) @@ -56,22 +75,68 @@ Mga pangkalahatang setting, system storage, backup management (export/import dat ## 🔧 CLI Tools -Isang-click na configuration para sa AI coding tool: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, at Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Mga Log ng Kahilingan +## 🤖 CLI Agents _(v2.0.11+)_ -Real-time na pag-log ng kahilingan gamit ang pag-filter ayon sa provider, modelo, account, at API key. Nagpapakita ng mga status code, paggamit ng token, latency, at mga detalye ng pagtugon. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Endpoint ng API +## 🌐 API Endpoint -Ang iyong pinag-isang API endpoint na may breakdown ng kakayahan: Mga Pagkumpleto ng Chat, Mga Pag-embed, Pagbuo ng Imahe, Muling Ranggo, Transkripsyon ng Audio, at mga nakarehistrong API key. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/phi/TROUBLESHOOTING.md b/docs/i18n/phi/TROUBLESHOOTING.md index 46e1dc62e7..120092d63c 100644 --- a/docs/i18n/phi/TROUBLESHOOTING.md +++ b/docs/i18n/phi/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Pag-troubleshoot +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Mga karaniwang problema at solusyon para sa OmniRoute. +Common problems and solutions for OmniRoute. --- -## Mabilis na Pag-aayos +## Quick Fixes -| Problema | Solusyon | -| ------------------------------------------------- | ---------------------------------------------------------------------------- | -| Unang login ay hindi gumagana | Lagyan ng check ang `INITIAL_PASSWORD` sa `.env` (default: `123456`) | -| Nagbubukas ang dashboard sa maling port | Itakda ang `PORT=20128` at `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Walang mga log ng kahilingan sa ilalim ng `logs/` | Itakda ang `ENABLE_REQUEST_LOGS=true` | -| EACCES: tinanggihan ang pahintulot | Itakda ang `DATA_DIR=/path/to/writable/dir` na i-override ang `~/.omniroute` | -| Hindi nagse-save ang diskarte sa pagruruta | Update sa v1.4.11+ (Zod schema fix para sa pagtitiyaga ng mga setting) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Mga Isyu sa Provider +## Provider Issues -### "Ang modelo ng wika ay hindi nagbigay ng mga mensahe" +### "Language model did not provide messages" -**Sanhi:** Naubos na ang quota ng provider. +**Cause:** Provider quota exhausted. -**Ayusin:** +**Fix:** -1. Suriin ang dashboard quota tracker -2. Gumamit ng combo na may fallback tier -3. Lumipat sa mas mura/libreng tier +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Paglilimita sa Rate +### Rate Limiting -**Dahil:** Naubos na ang quota ng subscription. +**Cause:** Subscription quota exhausted. -**Ayusin:** +**Fix:** -- Magdagdag ng fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Gamitin ang GLM/MiniMax bilang murang backup +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Nag-expire na ang OAuth Token +### OAuth Token Expired -Ang OmniRoute ay awtomatikong nagre-refresh ng mga token. Kung magpapatuloy ang mga isyu: +OmniRoute auto-refreshes tokens. If issues persist: -1. Dashboard → Provider → Kumonekta muli -2. Tanggalin at muling idagdag ang koneksyon ng provider +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Mga Isyu sa Ulap +## Cloud Issues -### Mga Error sa Cloud Sync +### Cloud Sync Errors -1. I-verify ang `BASE_URL` na mga puntos sa iyong running instance (hal., `http://localhost:20128`) -2. I-verify ang `CLOUD_URL` na mga puntos sa iyong cloud endpoint (hal., `https://omniroute.dev`) -3. Panatilihing nakahanay ang mga value ng `NEXT_PUBLIC_*` sa mga value sa gilid ng server +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Nagbabalik ng 500 +### Cloud `stream=false` Returns 500 -**Symptom:** `Unexpected token 'd'...` sa cloud endpoint para sa mga non-streaming na tawag. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Sanhi:** Ibinabalik ng Upstream ang SSE payload habang inaasahan ng kliyente ang JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Workaround:** Gamitin ang `stream=true` para sa mga direktang tawag sa cloud. Kasama sa lokal na runtime ang SSE→JSON fallback. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud Says Connected ngunit "Invalid API key" +### Cloud Says Connected but "Invalid API key" -1. Gumawa ng bagong key mula sa lokal na dashboard (`/api/keys`) -2. Patakbuhin ang cloud sync: Paganahin ang Cloud → Sync Now -3. Ang mga luma/hindi naka-sync na key ay maaari pa ring ibalik ang `401` sa cloud +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Mga Isyu sa Docker +## Docker Issues -### Hindi Naka-install ang Mga Palabas ng CLI Tool +### CLI Tool Shows Not Installed -1. Suriin ang mga field ng runtime: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Para sa portable mode: gumamit ng target ng imahe `runner-cli` (mga naka-bundle na CLI) -3. Para sa host mount mode: itakda ang `CLI_EXTRA_PATHS` at i-mount ang host bin directory bilang read-only -4. Kung `installed=true` at `runnable=false`: natagpuan ang binary ngunit nabigo ang healthcheck +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Mabilis na Runtime Validation +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Mga Isyu sa Gastos +## Cost Issues -### Mataas na Gastos +### High Costs -1. Suriin ang mga istatistika ng paggamit sa Dashboard → Paggamit -2. Ilipat ang pangunahing modelo sa GLM/MiniMax -3. Gumamit ng libreng tier (Gemini CLI, iFlow) para sa mga hindi kritikal na gawain -4. Magtakda ng mga badyet sa gastos sa bawat API key: Dashboard → API Keys → Badyet +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Pag-debug +## Debugging -### Paganahin ang Mga Log ng Kahilingan +### Enable Request Logs -Itakda ang `ENABLE_REQUEST_LOGS=true` sa iyong `.env` file. Lumilitaw ang mga log sa ilalim ng `logs/` na direktoryo. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Suriin ang Kalusugan ng Provider +### Check Provider Health ```bash # Health dashboard @@ -120,100 +120,135 @@ curl http://localhost:20128/api/monitoring/health ### Runtime Storage -- Pangunahing estado: `${DATA_DIR}/db.json` (mga provider, combo, alias, key, setting) -- Paggamit: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Mga log ng kahilingan: `/logs/...` (kapag `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Mga Isyu sa Circuit Breaker +## Circuit Breaker Issues -### Natigil ang provider sa OPEN na estado +### Provider stuck in OPEN state -Kapag ang circuit breaker ng provider ay BUKAS, ang mga kahilingan ay hinaharangan hanggang sa mag-expire ang cooldown. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Ayusin:** +**Fix:** -1. Pumunta sa **Dashboard → Settings → Resilience** -2. Suriin ang circuit breaker card para sa apektadong provider -3. I-click ang **I-reset Lahat** upang i-clear ang lahat ng mga breaker, o hintaying mag-expire ang cooldown -4. I-verify na available talaga ang provider bago i-reset +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Patuloy na binabadtrip ng provider ang circuit breaker +### Provider keeps tripping the circuit breaker -Kung ang isang provider ay paulit-ulit na pumasok sa OPEN state: +If a provider repeatedly enters OPEN state: -1. Suriin ang **Dashboard → Health → Provider Health** para sa pattern ng pagkabigo -2. Pumunta sa **Settings → Resilience → Provider Profiles** at taasan ang failure threshold -3. Suriin kung binago ng provider ang mga limitasyon ng API o nangangailangan ng muling pagpapatotoo -4. Suriin ang latency telemetry — ang mataas na latency ay maaaring magdulot ng mga pagkabigo batay sa timeout +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Mga Isyu sa Transkripsyon ng Audio +## Audio Transcription Issues -### Error sa "Hindi sinusuportahang modelo." +### "Unsupported model" error -- Tiyaking ginagamit mo ang tamang prefix: `deepgram/nova-3` o `assemblyai/best` -- I-verify na konektado ang provider sa **Dashboard → Mga Provider** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Nagbabalik ang transkripsyon na walang laman o nabigo +### Transcription returns empty or fails -- Suriin ang mga sinusuportahang format ng audio: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- I-verify na ang laki ng file ay nasa loob ng mga limitasyon ng provider (karaniwang <25MB) -- Suriin ang validity ng provider ng API key sa provider card +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Pag-debug ng Tagasalin +## Translator Debugging -Gamitin ang **Dashboard → Translator** upang i-debug ang mga isyu sa pagsasalin ng format: +Use **Dashboard → Translator** to debug format translation issues: -| Mode | Kailan Gagamitin | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| **Laruan** | Paghambingin ang mga format ng input/output nang magkatabi — i-paste ang isang nabigong kahilingan upang makita kung paano ito isinasalin | -| **Chat Tester** | Magpadala ng mga live na mensahe at siyasatin ang buong kahilingan/tugon payload kasama ang mga header | -| **Test Bench** | Magpatakbo ng mga batch test sa mga kumbinasyon ng format upang malaman kung aling mga pagsasalin ang sira | -| **Live Monitor** | Panoorin ang daloy ng kahilingan sa real-time upang mahuli ang mga pasulput-sulpot na isyu sa pagsasalin | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Mga karaniwang isyu sa format +### Common format issues -- **Hindi lumalabas ang mga tag ng pag-iisip** — Tingnan kung sinusuportahan ng target na provider ang pag-iisip at ang setting ng badyet sa pag-iisip -- **Pagbaba ng mga tawag sa tool** — Maaaring alisin ng ilang pagsasalin ng format ang mga hindi sinusuportahang field; i-verify sa Playground mode -- **System prompt nawawala** — Claude at Gemini handle system prompts magkaiba; suriin ang output ng pagsasalin -- **Nagbabalik ang SDK ng hilaw na string sa halip na object** — Naayos sa v1.1.0: tinatanggal na ngayon ng response sanitizer ang mga hindi karaniwang field (`x_groq`, `usage_breakdown`, atbp.) na nagdudulot ng mga pagkabigo sa pagpapatunay ng OpenAI SDK Pydantic -- **Tinatanggihan ng GLM/ERNIE ang `system` na tungkulin** — Naayos sa v1.1.0: awtomatikong pinagsasama ng role normalizer ang mga mensahe ng system sa mga mensahe ng user para sa mga hindi tugmang modelo -- **`developer` tungkulin ay hindi nakilala** — Naayos sa v1.1.0: awtomatikong na-convert sa `system` para sa mga hindi OpenAI na provider -- **`json_schema` hindi gumagana sa Gemini** — Naayos sa v1.1.0: `response_format` ay na-convert na ngayon sa Gemini's `responseMimeType` + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Mga Setting ng Katatagan +## Resilience Settings -### Hindi nagti-trigger ang limitasyon ng awtomatikong rate +### Auto rate-limit not triggering -- Nalalapat lang ang limitasyon ng awtomatikong rate sa mga provider ng API key (hindi OAuth/subscription) -- I-verify **Mga Setting → Resilience → Provider Profile** ay pinagana ang auto-rate-limit -- Suriin kung ibinabalik ng provider ang `429` status code o `Retry-After` header +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Pag-tune ng exponential backoff +### Tuning exponential backoff -Sinusuportahan ng mga profile ng provider ang mga setting na ito: +Provider profiles support these settings: -- **Base delay** — Paunang oras ng paghihintay pagkatapos ng unang pagkabigo (default: 1s) -- **Max na pagkaantala** — Maximum na limitasyon sa oras ng paghihintay (default: 30s) -- **Multiplier** — Magkano ang itataas na pagkaantala sa bawat magkakasunod na pagkabigo (default: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Anti-kulog na kawan +### Anti-thundering herd -Kapag maraming sabay-sabay na kahilingan ang tumama sa isang provider na limitado sa rate, gumagamit ang OmniRoute ng mutex + auto rate-limiting para i-serialize ang mga kahilingan at maiwasan ang mga pagkabigo ng cascading. Ito ay awtomatiko para sa mga API key provider. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Natigil pa rin? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Mga Isyu sa GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arkitektura**: Tingnan ang [link](ARCHITECTURE.md) para sa mga panloob na detalye -- **API Reference**: Tingnan ang [link](API_REFERENCE.md) para sa lahat ng endpoint -- **Dashboard ng Kalusugan**: Suriin ang **Dashboard → Kalusugan** para sa real-time na status ng system -- **Translator**: Gamitin ang **Dashboard → Translator** para i-debug ang mga isyu sa format +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/phi/USER_GUIDE.md b/docs/i18n/phi/USER_GUIDE.md index 6c924a5de8..5a043224df 100644 --- a/docs/i18n/phi/USER_GUIDE.md +++ b/docs/i18n/phi/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Gabay sa Gumagamit +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Kumpletong gabay para sa pag-configure ng mga provider, paggawa ng mga combo, pagsasama ng mga tool sa CLI, at pag-deploy ng OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Talaan ng mga Nilalaman +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Kumpletong gabay para sa pag-configure ng mga provider, paggawa ng mga combo, pa --- -## 💰 Pagpepresyo sa isang Sulyap +## 💰 Pricing at a Glance -| Tier | Provider | Gastos | I-reset ang Quota | Pinakamahusay Para sa | -| ------------------- | ----------------- | -------------------------- | -------------------- | ------------------------------ | -| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/buwan | 5h + lingguhan | Naka-subscribe na | -| | Codex (Plus/Pro) | $20-200/buwan | 5h + lingguhan | Mga user ng OpenAI | -| | Gemini CLI | **LIBRE** | 180K/buwan + 1K/araw | Lahat! | -| | GitHub Copilot | $10-19/buwan | Buwanang | Mga user ng GitHub | -| **🔑 API KEY** | DeepSeek | Magbayad sa bawat paggamit | Wala | Murang pangangatwiran | -| | Groq | Magbayad sa bawat paggamit | Wala | Napakabilis na hinuha | -| | xAI (Grok) | Magbayad sa bawat paggamit | Wala | Grok 4 na pangangatwiran | -| | Mistral | Magbayad sa bawat paggamit | Wala | Mga modelong naka-host sa EU | -| | Pagkagulo | Magbayad sa bawat paggamit | Wala | Search-augmented | -| | Magkasama AI | Magbayad sa bawat paggamit | Wala | Open-source na mga modelo | -| | Fireworks AI | Magbayad sa bawat paggamit | Wala | Mabilis na FLUX na mga larawan | -| | Cerebras | Magbayad sa bawat paggamit | Wala | Wafer-scale na bilis | -| | Cohere | Magbayad sa bawat paggamit | Wala | Command R+ RAG | -| | NVIDIA NIM | Magbayad sa bawat paggamit | Wala | Mga modelo ng enterprise | -| **💰 MURA** | GLM-4.7 | $0.6/1M | Araw-araw 10AM | Backup ng badyet | -| | MiniMax M2.1 | $0.2/1M | 5 oras na rolling | Pinaka murang opsyon | -| | Kimi K2 | $9/buwan flat | 10M token/buwan | Nahuhulaang gastos | -| **🆓 LIBRE** | iFlow | $0 | Walang limitasyong | 8 mga modelong libre | -| | Qwen | $0 | Walang limitasyong | 3 mga modelong libre | -| | Kiro | $0 | Walang limitasyong | Claude libre | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Pro Tip:** Magsimula sa Gemini CLI (180K libre/buwan) + iFlow (walang limitasyong libre) combo = $0 na halaga! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- ## 🎯 Use Cases -### Case 1: "May subscription ako sa Claude Pro" +### Case 1: "I have Claude Pro subscription" -**Problema:** Nag-e-expire ang quota nang hindi nagamit, mga limitasyon sa rate sa panahon ng mabigat na coding +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Case 2: "Gusto ko ng zero cost" +### Case 2: "I want zero cost" -**Problema:** Hindi kayang bayaran ang mga subscription, kailangan ng maaasahang AI coding +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Case 3: "Kailangan ko ng 24/7 coding, walang mga pagkaantala" +### Case 3: "I need 24/7 coding, no interruptions" -**Problema:** Mga deadline, hindi kayang bayaran ang downtime +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Kaso 4: "Gusto ko ng LIBRENG AI sa OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Problema:** Kailangan ng AI assistant sa mga app sa pagmemensahe, ganap na libre +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Setup ng Provider +## 📖 Provider Setup -### 🔐 Mga Tagabigay ng Subscription +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Pro Tip:** Gamitin ang Opus para sa mga kumplikadong gawain, Soneto para sa bilis. Sinusubaybayan ng OmniRoute ang quota bawat modelo! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (LIBRE 180K/buwan!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,7 +152,7 @@ Models: gc/gemini-2.5-pro ``` -**Pinakamahusay na Halaga:** Malaking libreng tier! Gamitin ito bago ang mga bayad na tier. +**Best Value:** Huge free tier! Use this before paid tiers. #### GitHub Copilot @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Mga Murang Provider +### 💰 Cheap Providers -#### GLM-4.7 (Araw-araw na pag-reset, $0.6/1M) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Mag-sign up: [Zhipu AI](https://open.bigmodel.cn/) -2. Kumuha ng API key mula sa Coding Plan -3. Dashboard → Magdagdag ng API Key: Provider: `glm`, API Key: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Gamitin:** `glm/glm-4.7` — **Pro Tip:** Nag-aalok ang Coding Plan ng 3× na quota sa 1/7 na halaga! I-reset araw-araw 10:00 AM. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. #### MiniMax M2.1 (5h reset, $0.20/1M) -1. Mag-sign up: [MiniMax](https://www.minimax.io/) -2. Kunin ang API key → Dashboard → Magdagdag ng API Key +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Gamitin:** `minimax/MiniMax-M2.1` — **Pro Tip:** Pinakamamurang opsyon para sa mahabang konteksto (1M token)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! #### Kimi K2 ($9/month flat) -1. Mag-subscribe: [Moonshot AI](https://platform.moonshot.ai/) -2. Kunin ang API key → Dashboard → Magdagdag ng API Key +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Gamitin:** `kimi/kimi-latest` — **Pro Tip:** Nakapirming $9/buwan para sa 10M token = $0.90/1M epektibong gastos! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 LIBRENG Provider +### 🆓 FREE Providers -#### iFlow (8 LIBRENG modelo) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 LIBRENG modelo) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude LIBRE) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Mga combo +## 🎨 Combos -### Halimbawa 1: I-maximize ang Subscription → Murang Backup +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Halimbawa 2: Libre-Lamang (Zero na Gastos) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,7 +249,7 @@ Cost: $0 forever! --- -## 🔧 Pagsasama ng CLI +## 🔧 CLI Integration ### Cursor IDE @@ -262,7 +262,7 @@ Settings → Models → Advanced: ### Claude Code -I-edit ang `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -I-edit ang `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ I-edit ang `~/.openclaw/openclaw.json`: } ``` -**O gumamit ng Dashboard:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Magpatuloy / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -318,6 +318,25 @@ Model: cc/claude-opus-4-6 ## 🚀 Deployment +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + ### VPS Deployment ```bash @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,39 +403,42 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Para sa host-integrated mode na may mga CLI binary, tingnan ang seksyong Docker sa mga pangunahing doc. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Mga Variable ng Environment +### Environment Variables -| Variable | Default | Paglalarawan | -| --------------------- | ------------------------------------ | ------------------------------------------------------------------ | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**pagbabago sa produksyon**) | -| `INITIAL_PASSWORD` | `123456` | Unang login password | -| `DATA_DIR` | `~/.omniroute` | Direktoryo ng data (db, paggamit, mga log) | -| `PORT` | default na framework | Port ng serbisyo (`20128` sa mga halimbawa) | -| `HOSTNAME` | default na framework | Bind host (Docker default sa `0.0.0.0`) | -| `NODE_ENV` | default na runtime | Itakda ang `production` para sa pag-deploy | -| `BASE_URL` | `http://localhost:20128` | Panloob na base URL sa gilid ng server | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret para sa mga nabuong API key | -| `REQUIRE_API_KEY` | `false` | Ipatupad ang Bearer API key sa `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Pinapagana ang mga log ng kahilingan/tugon | -| `AUTH_COOKIE_SECURE` | `false` | Pilitin ang `Secure` auth cookie (sa likod ng HTTPS reverse proxy) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Para sa buong environment variable reference, tingnan ang [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Mga Magagamit na Modelo +## 📊 Available Models
-Tingnan ang lahat ng available na modelo +View all available models **Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — LIBRE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` @@ -387,11 +446,11 @@ Para sa buong environment variable reference, tingnan ang [README](../README.md) **MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — LIBRE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — LIBRE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — LIBRE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,9 +460,9 @@ Para sa buong environment variable reference, tingnan ang [README](../README.md) **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Pagkakagulo (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Magkasama AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` **Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` @@ -417,11 +476,11 @@ Para sa buong environment variable reference, tingnan ang [README](../README.md) --- -## 🧩 Mga Advanced na Tampok +## 🧩 Advanced Features -### Mga Custom na Modelo +### Custom Models -Magdagdag ng anumang ID ng modelo sa anumang provider nang hindi naghihintay ng update ng app: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -O gamitin ang Dashboard: **Mga Provider → [Provider] → Mga Custom na Modelo**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Nakalaang Mga Ruta ng Provider +### Dedicated Provider Routes -Direktang iruta ang mga kahilingan sa isang partikular na provider na may pagpapatunay ng modelo: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,7 +504,7 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Ang prefix ng provider ay awtomatikong idinaragdag kung nawawala. Ang mga hindi tugmang modelo ay nagbabalik ng `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. ### Network Proxy Configuration @@ -471,68 +530,68 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ curl http://localhost:20128/api/models/catalog ``` -Ibinabalik ang mga modelong nakapangkat ayon sa provider na may mga uri (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). ### Cloud Sync -- I-sync ang mga provider, combo, at mga setting sa mga device -- Awtomatikong pag-sync sa background na may timeout + mabilis na mabibigo -- Mas gusto ang server-side `BASE_URL`/`CLOUD_URL` sa produksyon +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production ### LLM Gateway Intelligence (Phase 9) -- **Semantic Cache** — Auto-cache non-streaming, temperature=0 na tugon (bypass gamit ang `X-OmniRoute-No-Cache: true`) -- **Request Idempotency** — Nagde-deduplicate ng mga kahilingan sa loob ng 5s sa pamamagitan ng `Idempotency-Key` o `X-Request-Id` header -- **Pagsubaybay sa Pag-unlad** — Mag-opt-in sa SSE `event: progress` na mga kaganapan sa pamamagitan ng `X-OmniRoute-Progress: true` header +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Palaruan ng Tagasalin +### Translator Playground -Access sa pamamagitan ng **Dashboard → Translator**. I-debug at i-visualize kung paano isinasalin ng OmniRoute ang mga kahilingan sa API sa pagitan ng mga provider. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Mode | Layunin | -| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -| **Laruan** | Pumili ng pinagmulan/target na mga format, i-paste ang isang kahilingan, at makita agad ang isinaling output | -| **Chat Tester** | Magpadala ng mga mensahe sa live chat sa pamamagitan ng proxy at siyasatin ang buong cycle ng kahilingan/pagtugon | -| **Test Bench** | Magpatakbo ng mga batch test sa maraming kumbinasyon ng format upang i-verify ang kawastuhan ng pagsasalin | -| **Live Monitor** | Manood ng mga real-time na pagsasalin habang dumadaloy ang mga kahilingan sa pamamagitan ng proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Mga kaso ng paggamit:** +**Use cases:** -- I-debug kung bakit nabigo ang isang partikular na kumbinasyon ng kliyente/provider -- I-verify na ang mga tag ng pag-iisip, mga tawag sa tool, at mga prompt ng system ay naisalin nang tama -- Ihambing ang mga pagkakaiba sa format sa pagitan ng mga format ng OpenAI, Claude, Gemini, at Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Mga Istratehiya sa Pagruruta +### Routing Strategies -I-configure sa pamamagitan ng **Dashboard → Mga Setting → Pagruruta**. +Configure via **Dashboard → Settings → Routing**. -| Diskarte | Paglalarawan | -| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Punan muna** | Gumagamit ng mga account sa pagkakasunud-sunod ng priyoridad — pinangangasiwaan ng pangunahing account ang lahat ng kahilingan hanggang sa hindi magamit | -| **Round Robin** | Umiikot sa lahat ng account na may na-configure na malagkit na limitasyon (default: 3 tawag sa bawat account) | -| **P2C (Power of Two Choices)** | Pumili ng 2 random na account at ruta patungo sa mas malusog — binabalanse ang load nang may kamalayan sa kalusugan | -| **Random** | Random na pumipili ng account para sa bawat kahilingan gamit ang Fisher-Yates shuffle | -| **Hindi gaanong Nagamit** | Mga ruta patungo sa account na may pinakamatandang `lastUsedAt` timestamp, na namamahagi ng trapiko nang pantay-pantay | -| **Na-optimize ang Gastos** | Mga ruta patungo sa account na may pinakamababang halaga ng priyoridad, na nag-o-optimize para sa mga provider na may pinakamababang halaga | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Mga Alyas ng Modelong Wildcard +#### Wildcard Model Aliases -Lumikha ng mga pattern ng wildcard upang i-remap ang mga pangalan ng modelo: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Sinusuportahan ng mga wildcard ang `*` (anumang character) at `?` (solong character). +Wildcards support `*` (any characters) and `?` (single character). -#### Fallback Chain +#### Fallback Chains -Tukuyin ang mga pandaigdigang fallback chain na nalalapat sa lahat ng kahilingan: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Resilience at Circuit Breaker +### Resilience & Circuit Breakers -I-configure sa pamamagitan ng **Dashboard → Mga Setting → Resilience**. +Configure via **Dashboard → Settings → Resilience**. -Ang OmniRoute ay nagpapatupad ng pagiging matatag sa antas ng provider na may apat na bahagi: +OmniRoute implements provider-level resilience with four components: -1. **Provider Profile** — Configuration ng bawat provider para sa: - - Failure threshold (ilang pagkabigo bago buksan) - - Tagal ng cooldown +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration - Rate limit detection sensitivity - - Exponential backoff na mga parameter + - Exponential backoff parameters -2. **Editable Rate Limits** — System-level defaults configurable sa dashboard: - - **Requests Per Minute (RPM)** — Mga maximum na kahilingan kada minuto bawat account - - **Min Time Between Requests** — Minimum na agwat sa millisecond sa pagitan ng mga kahilingan - - **Max Kasabay na Kahilingan** — Pinakamataas na sabay-sabay na kahilingan sa bawat account - - I-click ang **I-edit** upang baguhin, pagkatapos ay **I-save** o **Kanselahin**. Nananatili ang mga halaga sa pamamagitan ng resilience API. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** — Sinusubaybayan ang mga pagkabigo sa bawat provider at awtomatikong bubuksan ang circuit kapag naabot ang isang threshold: - - **SARADO** (Healthy) — Normal na dumadaloy ang mga kahilingan - - **OPEN** — Pansamantalang naka-block ang provider pagkatapos ng paulit-ulit na pagkabigo - - **HALF_OPEN** — Pagsubok kung nakabawi na ang provider +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Mga Patakaran at Mga Naka-lock na Identifier** — Nagpapakita ng status ng circuit breaker at mga naka-lock na identifier na may kakayahan sa force-unlock. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Awtomatikong Pagtukoy sa Limitasyon ng Rate** — Sinusubaybayan ang `429` at `Retry-After` na mga header upang aktibong maiwasang maabot ang mga limitasyon sa rate ng provider. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Pro Tip:** Gamitin ang **I-reset Lahat** na button para i-clear ang lahat ng mga circuit breaker at cooldown kapag gumaling ang isang provider mula sa isang outage. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Pag-export / Pag-import ng Database +### Database Export / Import -Pamahalaan ang mga backup ng database sa **Dashboard → Mga Setting → System at Storage**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Aksyon | Paglalarawan | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **I-export ang Database** | Dina-download ang kasalukuyang database ng SQLite bilang isang `.sqlite` file | -| **I-export Lahat (.tar.gz)** | Nagda-download ng buong backup na archive kabilang ang: database, mga setting, combo, mga koneksyon sa provider (walang mga kredensyal), metadata ng API key | -| **Import Database** | Mag-upload ng `.sqlite` file upang palitan ang kasalukuyang database. Awtomatikong nagagawa ang isang pre-import na backup | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Import Validation:** Ang na-import na file ay napatunayan para sa integridad (SQLite pragma check), kinakailangang mga talahanayan (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), at laki (max 100MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Mga Kaso ng Paggamit:** +**Use Cases:** -- I-migrate ang OmniRoute sa pagitan ng mga machine -- Lumikha ng mga panlabas na backup para sa pagbawi ng kalamidad -- Magbahagi ng mga pagsasaayos sa pagitan ng mga miyembro ng koponan (i-export lahat → ibahagi ang archive) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Dashboard ng Mga Setting +### Settings Dashboard -Ang pahina ng mga setting ay isinaayos sa 5 tab para sa madaling pag-navigate: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Mga Nilalaman | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| **Seguridad** | Mga setting ng Login/Password, IP Access Control, API auth para sa `/models`, at Provider Blocking | -| **Pagruruta** | Pandaigdigang diskarte sa pagruruta (6 na opsyon), wildcard model alias, fallback chain, combo default | -| **Katatagan** | Mga profile ng provider, mga limitasyon sa nae-edit na rate, status ng circuit breaker, mga patakaran at mga naka-lock na identifier | -| **AI** | Pag-iisip ng configuration ng badyet, pandaigdigang system prompt injection, prompt cache stats | -| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Pamamahala ng Mga Gastos at Badyet +### Costs & Budget Management -Access sa pamamagitan ng **Dashboard → Mga Gastos**. +Access via **Dashboard → Costs**. -| Tab | Layunin | -| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| **Badyet** | Magtakda ng mga limitasyon sa paggastos sa bawat API key na may pang-araw-araw/lingguhan/buwanang mga badyet at real-time na pagsubaybay | -| **Pagpepresyo** | Tingnan at i-edit ang mga entry sa pagpepresyo ng modelo — cost per 1K input/output token bawat provider | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Pagsubaybay sa Gastos:** Ang bawat kahilingan ay nagtatala ng paggamit ng token at kinakalkula ang gastos gamit ang talahanayan ng pagpepresyo. Tingnan ang mga breakdown sa **Dashboard → Paggamit** ayon sa provider, modelo, at API key. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Transkripsyon ng Audio +### Audio Transcription -Sinusuportahan ng OmniRoute ang audio transcription sa pamamagitan ng OpenAI-compatible na endpoint: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Mga available na provider: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Mga sinusuportahang format ng audio: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Mga Diskarte sa Pagbalanse ng Combo +### Combo Balancing Strategies -I-configure ang per-combo balancing sa **Dashboard → Combos → Create/Edit → Strategy**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Diskarte | Paglalarawan | -| ------------------------- | -------------------------------------------------------------------------------------------------- | -| **Round-Robin** | Umiikot sa mga modelo nang sunud-sunod | -| **Priyoridad** | Palaging sinusubukan ang unang modelo; bumabalik lamang sa error | -| **Random** | Pumipili ng random na modelo mula sa combo para sa bawat kahilingan | -| **Tinimbang** | Mga rutang proporsyonal batay sa mga nakatalagang timbang sa bawat modelo | -| **Hindi gaanong Nagamit** | Mga ruta patungo sa modelo na may kaunting mga kamakailang kahilingan (gumagamit ng combo metrics) | -| **Cost-Optimized** | Mga ruta patungo sa pinakamurang available na modelo (gumagamit ng talahanayan ng pagpepresyo) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Maaaring itakda ang mga global combo default sa **Dashboard → Settings → Routing → Combo Defaults**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- ### Health Dashboard -Access sa pamamagitan ng **Dashboard → Health**. Real-time na pangkalahatang-ideya ng kalusugan ng system na may 6 na card: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Card | Ano ang Ipinakikita Nito | -| -------------------------- | ----------------------------------------------------------------------------------- | -| **System Status** | Uptime, bersyon, paggamit ng memorya, direktoryo ng data | -| **Kalusugan ng Provider** | Status ng circuit breaker ng bawat provider (Sarado/Bukas/Kalahating Bukas) | -| **Mga Limitasyon sa Rate** | Mga cooldown sa limitasyon ng aktibong rate sa bawat account na may natitirang oras | -| **Mga Aktibong Lockout** | Pansamantalang na-block ang mga provider ng patakaran sa lockout | -| **Signature Cache** | Deduplication cache stats (aktibong key, hit rate) | -| **Latency Telemetry** | p50/p95/p99 latency aggregation bawat provider | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Pro Tip:** Awtomatikong nagre-refresh ang page ng Health bawat 10 segundo. Gamitin ang circuit breaker card upang matukoy kung aling mga provider ang nakakaranas ng mga isyu. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/pl/API_REFERENCE.md b/docs/i18n/pl/API_REFERENCE.md index 9a340db6f1..b795722c11 100644 --- a/docs/i18n/pl/API_REFERENCE.md +++ b/docs/i18n/pl/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Dokumentacja API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Pełna dokumentacja dla wszystkich punktów końcowych API OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Spis treści +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Pełna dokumentacja dla wszystkich punktów końcowych API OmniRoute. --- -## Zakończenie czatu +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Niestandardowe nagłówki +### Custom Headers -| Nagłówek | Kierunek | Opis | -| ------------------------ | --------- | ------------------------------------------------- | -| `X-OmniRoute-No-Cache` | Prośba | Ustaw na `true`, aby ominąć pamięć podręczną | -| `X-OmniRoute-Progress` | Prośba | Ustaw na `true` dla zdarzeń postępu | -| `Idempotency-Key` | Prośba | Klucz deduplikacji (okno 5s) | -| `X-Request-Id` | Prośba | Alternatywny klucz deduplikacji | -| `X-OmniRoute-Cache` | Odpowiedź | `HIT` lub `MISS` (bez przesyłania strumieniowego) | -| `X-OmniRoute-Idempotent` | Odpowiedź | `true` w przypadku deduplikacji | -| `X-OmniRoute-Progress` | Odpowiedź | `enabled`, jeśli śledzenie postępu | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Osadzenia +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Dostępni dostawcy: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Generowanie obrazu +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Dostępni dostawcy: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Lista modeli +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Punkty końcowe zgodności +## Compatibility Endpoints -| Metoda | Ścieżka | Formatuj | -| -------- | --------------------------- | ---------------------------- | -| POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Antropiczny | -| POST | `/v1/responses` | Odpowiedzi OpenAI | -| POST | `/v1/embeddings` | OpenAI | -| POST | `/v1/images/generations` | OpenAI | -| OTRZYMAJ | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Antropiczny | -| OTRZYMAJ | `/v1beta/models` | Bliźnięta | -| POST | `/v1beta/models/{...path}` | Bliźnięta generują zawartość | -| POST | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Dedykowane trasy dostawców +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Prefiks dostawcy jest dodawany automatycznie, jeśli go brakuje. Niedopasowane modele zwracają `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Pamięć podręczna semantyczna +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Przykład odpowiedzi: +Response example: ```json { @@ -162,154 +162,164 @@ Przykład odpowiedzi: --- -## Panel i zarządzanie +## Dashboard & Management -### Uwierzytelnianie +### Authentication -| Punkt końcowy | Metoda | Opis | -| ----------------------------- | ------------- | --------------------------- | -| `/api/auth/login` | POST | Zaloguj | -| `/api/auth/logout` | POST | Wyloguj | -| `/api/settings/require-login` | POBIERZ/WSTAW | Przełącz wymagane logowanie | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Zarządzanie dostawcami +### Provider Management -| Punkt końcowy | Metoda | Opis | -| ---------------------------- | ----------------- | ----------------------------- | -| `/api/providers` | POBIERZ/WYŚLIJ | Lista / tworzenie dostawców | -| `/api/providers/[id]` | POBIERZ/PUT/USUŃ | Zarządzaj dostawcą | -| `/api/providers/[id]/test` | POST | Połączenie z dostawcą testów | -| `/api/providers/[id]/models` | OTRZYMAJ | Lista modeli dostawców | -| `/api/providers/validate` | POST | Sprawdź konfigurację dostawcy | -| `/api/provider-nodes*` | Różne | Zarządzanie węzłami dostawcy | -| `/api/provider-models` | POBIERZ/POST/USUŃ | Modele niestandardowe | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Przepływy OAuth +### OAuth Flows -| Punkt końcowy | Metoda | Opis | -| -------------------------------- | ------ | ------------------------------ | -| `/api/oauth/[provider]/[action]` | Różne | OAuth specyficzne dla dostawcy | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Routing i konfiguracja +### Routing & Config -| Punkt końcowy | Metoda | Opis | -| --------------------- | -------------- | -------------------------------------- | -| `/api/models/alias` | POBIERZ/WYŚLIJ | Aliasy modeli | -| `/api/models/catalog` | OTRZYMAJ | Wszystkie modele według dostawcy + typ | -| `/api/combos*` | Różne | Zarządzanie kombinacjami | -| `/api/keys*` | Różne | Zarządzanie kluczami API | -| `/api/pricing` | OTRZYMAJ | Ceny modeli | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Wykorzystanie i analityka +### Usage & Analytics -| Punkt końcowy | Metoda | Opis | -| --------------------------- | -------- | ----------------------------- | -| `/api/usage/history` | OTRZYMAJ | Historia użytkowania | -| `/api/usage/logs` | OTRZYMAJ | Dzienniki użytkowania | -| `/api/usage/request-logs` | OTRZYMAJ | Dzienniki na poziomie żądania | -| `/api/usage/[connectionId]` | OTRZYMAJ | Użycie na połączenie | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Ustawienia +### Settings -| Punkt końcowy | Metoda | Opis | -| ------------------------------- | ------------- | ---------------------------------------- | -| `/api/settings` | POBIERZ/WSTAW | Ustawienia ogólne | -| `/api/settings/proxy` | POBIERZ/WSTAW | Konfiguracja serwera proxy sieci | -| `/api/settings/proxy/test` | POST | Testuj połączenie proxy | -| `/api/settings/ip-filter` | POBIERZ/WSTAW | Lista dozwolonych/blokowanych adresów IP | -| `/api/settings/thinking-budget` | POBIERZ/WSTAW | Rozumowanie budżetu symbolicznego | -| `/api/settings/system-prompt` | POBIERZ/WSTAW | Globalny monit systemowy | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Monitorowanie +### Monitoring -| Punkt końcowy | Metoda | Opis | -| ------------------------ | ------------ | --------------------------------------- | -| `/api/sessions` | OTRZYMAJ | Śledzenie aktywnej sesji | -| `/api/rate-limits` | OTRZYMAJ | Limity stawek za konto | -| `/api/monitoring/health` | OTRZYMAJ | Kontrola stanu zdrowia | -| `/api/cache` | POBIERZ/USUŃ | Statystyki pamięci podręcznej / wyczyść | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Kopia zapasowa i eksport/import +### Backup & Export/Import -| Punkt końcowy | Metoda | Opis | -| --------------------------- | -------- | -------------------------------------------------- | -| `/api/db-backups` | OTRZYMAJ | Lista dostępnych kopii zapasowych | -| `/api/db-backups` | POSTAW | Utwórz ręczną kopię zapasową | -| `/api/db-backups` | POST | Przywróć z określonej kopii zapasowej | -| `/api/db-backups/export` | OTRZYMAJ | Pobierz bazę danych jako plik .sqlite | -| `/api/db-backups/import` | POST | Prześlij plik .sqlite, aby zastąpić bazę danych | -| `/api/db-backups/exportAll` | OTRZYMAJ | Pobierz pełną kopię zapasową jako archiwum .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Synchronizacja z chmurą +### Cloud Sync -| Punkt końcowy | Metoda | Opis | -| ---------------------- | ------ | --------------------------------- | -| `/api/sync/cloud` | Różne | Operacje synchronizacji w chmurze | -| `/api/sync/initialize` | POST | Zainicjuj synchronizację | -| `/api/cloud/*` | Różne | Zarządzanie chmurą | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Narzędzia CLI +### CLI Tools -| Punkt końcowy | Metoda | Opis | -| ---------------------------------- | -------- | -------------------------------- | -| `/api/cli-tools/claude-settings` | OTRZYMAJ | Stan CLI Claude'a | -| `/api/cli-tools/codex-settings` | OTRZYMAJ | Stan CLI Kodeksu | -| `/api/cli-tools/droid-settings` | OTRZYMAJ | Stan CLI droida | -| `/api/cli-tools/openclaw-settings` | OTRZYMAJ | Stan interfejsu CLI OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | OTRZYMAJ | Ogólne środowisko wykonawcze CLI | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Odpowiedzi CLI obejmują: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Odporność i limity szybkości +### ACP Agents -| Punkt końcowy | Metoda | Opis | -| ----------------------- | ------------- | ---------------------------------------- | -| `/api/resilience` | POBIERZ/WSTAW | Pobierz/zaktualizuj profile odporności | -| `/api/resilience/reset` | POST | Zresetuj wyłączniki automatyczne | -| `/api/rate-limits` | OTRZYMAJ | Stan limitu stawek za konto | -| `/api/rate-limit` | OTRZYMAJ | Konfiguracja globalnego limitu szybkości | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Obliczenia +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Punkt końcowy | Metoda | Opis | -| ------------- | -------------- | ----------------------------------------------------- | -| `/api/evals` | POBIERZ/WYŚLIJ | Lista zestawów ewaluacyjnych / uruchomienie ewaluacji | +### Resilience & Rate Limits -### Zasady +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Punkt końcowy | Metoda | Opis | -| --------------- | ----------------- | --------------------------- | -| `/api/policies` | POBIERZ/POST/USUŃ | Zarządzaj zasadami routingu | +### Evals -### Zgodność +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Punkt końcowy | Metoda | Opis | -| --------------------------- | -------- | -------------------------------------- | -| `/api/compliance/audit-log` | OTRZYMAJ | Dziennik audytu zgodności (ostatnie N) | +### Policies -### v1beta (kompatybilny z Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Punkt końcowy | Metoda | Opis | -| -------------------------- | -------- | ----------------------------------------- | -| `/v1beta/models` | OTRZYMAJ | Lista modeli w formacie Gemini | -| `/v1beta/models/{...path}` | POST | Bliźnięta `generateContent` punkt końcowy | +### Compliance -Te punkty końcowe odzwierciedlają format API Gemini dla klientów, którzy oczekują natywnej zgodności Gemini SDK. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### Wewnętrzne/systemowe interfejsy API +### v1beta (Gemini-Compatible) -| Punkt końcowy | Metoda | Opis | -| --------------- | -------- | ---------------------------------------------------------------------- | -| `/api/init` | OTRZYMAJ | Kontrola inicjalizacji aplikacji (używana przy pierwszym uruchomieniu) | -| `/api/tags` | OTRZYMAJ | Tagi modeli zgodnych z Ollama (dla klientów Ollama) | -| `/api/restart` | POST | Wywołaj łagodny restart serwera | -| `/api/shutdown` | POST | Wywołaj łagodne zamknięcie serwera | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Uwaga:** Te punkty końcowe są używane wewnętrznie przez system lub w celu zapewnienia zgodności z klientem Ollama. Zwykle nie są one wywoływane przez użytkowników końcowych. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Transkrypcja audio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transkrypuj pliki audio za pomocą Deepgram lub AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Prośba:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Odpowiedź:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Obsługiwani dostawcy:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Obsługiwane formaty:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Zgodność z Ollamą +## Ollama Compatibility -Dla klientów korzystających z formatu API Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Żądania są automatycznie tłumaczone pomiędzy formatami Ollama i formatami wewnętrznymi. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetria +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Odpowiedź:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Budżet +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Dostępność modelu +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Przetwarzanie żądania +## Request Processing -1. Klient wysyła żądanie do `/v1/*` -2. Wywołania obsługi tras `handleChat`, `handleEmbedding`, `handleAudioTranscription` lub `handleImageGeneration` -3. Model został rozwiązany (bezpośredni dostawca/model lub alias/kombinacja) -4. Poświadczenia wybrane z lokalnej bazy danych z filtrowaniem dostępności kont -5. Dla czatu: `handleChatCore` — wykrywanie formatu, tłumaczenie, sprawdzanie pamięci podręcznej, sprawdzanie idempotencji -6. Wykonawca dostawcy wysyła żądanie upstream -7. Odpowiedź przetłumaczona z powrotem na format klienta (czat) lub zwrócona w niezmienionej postaci (osadzone elementy/obrazy/audio) -8. Zarejestrowano użycie/rejestrowanie -9. Rezerwa ma zastosowanie w przypadku błędów zgodnie z zasadami kombinacji +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Pełne odniesienie do architektury: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Uwierzytelnianie +## Authentication -- Trasy panelu kontrolnego (`/dashboard/*`) korzystają z pliku cookie `auth_token` -- Logowanie wykorzystuje zapisany skrót hasła; powrót do `INITIAL_PASSWORD` -- `requireLogin` przełączane poprzez `/api/settings/require-login` -- `/v1/*` trasy opcjonalnie wymagają klucza API nośnika, gdy `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/pl/ARCHITECTURE.md b/docs/i18n/pl/ARCHITECTURE.md index bb0d6d7757..258d62df53 100644 --- a/docs/i18n/pl/ARCHITECTURE.md +++ b/docs/i18n/pl/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Architektura OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Ostatnia aktualizacja: 2026-02-18_ +_Last updated: 2026-03-04_ -## Podsumowanie wykonawcze +## Executive Summary -OmniRoute to lokalna brama routingu AI i pulpit nawigacyjny zbudowany w oparciu o Next.js. -Zapewnia pojedynczy punkt końcowy zgodny z OpenAI (`/v1/*`) i kieruje ruch do wielu dostawców nadrzędnych z tłumaczeniem, rezerwą, odświeżaniem tokenów i śledzeniem użycia. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Podstawowe możliwości: +Core capabilities: -- Powierzchnia API kompatybilna z OpenAI dla CLI/narzędzi (28 dostawców) -- Tłumaczenie żądań/odpowiedzi w różnych formatach dostawców -- Awaryjna kombinacja modeli (sekwencja wielu modeli) -- Rezerwa awaryjna na poziomie konta (wiele kont na dostawcę) -- Zarządzanie połączeniem dostawcy klucza OAuth + API -- Generowanie osadzania poprzez `/v1/embeddings` (6 dostawców, 9 modeli) -- Generowanie obrazu poprzez `/v1/images/generations` (4 dostawców, 9 modeli) -- Pomyśl o analizie tagów (`...`) pod kątem modeli wnioskowania -- Oczyszczanie odpowiedzi w celu zapewnienia ścisłej zgodności z OpenAI SDK -- Normalizacja ról (programista → system, system → użytkownik) w celu zapewnienia zgodności między dostawcami -- Strukturalna konwersja danych wyjściowych (json_schema → Gemini respondSchema) -- Lokalna trwałość dostawców, kluczy, aliasów, kombinacji, ustawień, cen -- Śledzenie wykorzystania/kosztów i rejestrowanie żądań -- Opcjonalna synchronizacja w chmurze dla synchronizacji wielu urządzeń/stanów -- Lista dozwolonych/blokowanych adresów IP do kontroli dostępu do API -- Myślenie o zarządzaniu budżetem (przejściowe/automatyczne/niestandardowe/adaptacyjne) -- Globalny system natychmiastowego wstrzyknięcia -- Śledzenie sesji i pobieranie odcisków palców -- Ulepszone ograniczenie stawek dla konta z profilami specyficznymi dla dostawcy -- Wzór wyłącznika zapewniający odporność dostawcy -- Ochrona stada przed piorunami z blokadą mutex -- Pamięć podręczna deduplikacji żądań oparta na sygnaturach -- Warstwa domeny: dostępność modelu, zasady kosztów, polityka awaryjna, polityka blokad -- Trwałość stanu domeny (pamięć podręczna zapisu SQLite dla błędów awaryjnych, budżetów, blokad, wyłączników automatycznych) -- Silnik polityki do scentralizowanej oceny wniosków (blokada → budżet → rezerwa) - — Żądaj telemetrii z agregacją opóźnień p50/p95/p99 -- Identyfikator korelacji (X-Request-Id) do śledzenia od końca do końca -- Rejestrowanie audytu zgodności z możliwością rezygnacji dla każdego klucza API -- Ramy ewaluacyjne dla zapewnienia jakości LLM -- Pulpit nawigacyjny interfejsu użytkownika Resilience ze statusem wyłącznika automatycznego w czasie rzeczywistym -- Modułowi dostawcy OAuth (12 indywidualnych modułów pod `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Podstawowy model środowiska wykonawczego: +Primary runtime model: -- Trasy aplikacji Next.js w `src/app/api/*` implementują zarówno interfejsy API pulpitu nawigacyjnego, jak i interfejsy API zgodności -- Wspólny rdzeń SSE/routingu w `src/sse/*` + `open-sse/*` obsługuje wykonywanie dostawcy, tłumaczenie, przesyłanie strumieniowe, rezerwę i wykorzystanie +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Zakres i granice +## Scope and Boundaries -### W zakresie +### In Scope -- Środowisko wykonawcze bramy lokalnej -- Interfejsy API zarządzania pulpitem nawigacyjnym -- Uwierzytelnianie dostawcy i odświeżanie tokena -- Poproś o tłumaczenie i przesyłanie strumieniowe SSE -- Stan lokalny + trwałość użytkowania -- Opcjonalna orkiestracja synchronizacji w chmurze +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Poza zakresem +### Out of Scope -- Wdrożenie usługi w chmurze za `NEXT_PUBLIC_CLOUD_URL` -- Umowa SLA dostawcy/płaszczyzna kontroli poza procesem lokalnym -- Same zewnętrzne pliki binarne CLI (Claude CLI, Codex CLI itp.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Kontekst systemu wysokiego poziomu +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Podstawowe komponenty wykonawcze +## Core Runtime Components -## 1) API i warstwa routingu (trasy aplikacji Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Główne katalogi: +Main directories: -- `src/app/api/v1/*` i `src/app/api/v1beta/*` dla interfejsów API zgodności -- `src/app/api/*` dla interfejsów API zarządzania/konfiguracji -- Następne przepisanie w `next.config.mjs` mapie `/v1/*` na `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Ważne ścieżki kompatybilności: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — zawiera niestandardowe modele z `custom: true` -- `src/app/api/v1/embeddings/route.ts` — generacja osadzania (6 dostawców) -- `src/app/api/v1/images/generations/route.ts` — generowanie obrazu (4+ dostawców, w tym Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedykowany czat dla każdego dostawcy -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedykowane osadzanie dla poszczególnych dostawców -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — obrazy dedykowane dla poszczególnych dostawców +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Domeny zarządzania: +Management domains: -- Autoryzacja/ustawienia: `src/app/api/auth/*`, `src/app/api/settings/*` -- Dostawcy/połączenia: `src/app/api/providers*` -- Węzły dostawcy: `src/app/api/provider-nodes*` -- Modele niestandardowe: `src/app/api/provider-models` (GET/POST/DELETE) -- Katalog modeli: `src/app/api/models/catalog` (GET) -- Konfiguracja proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Klucze/aliasy/kombinacje/ceny: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Użycie: `src/app/api/usage/*` -- Synchronizacja/chmura: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Pomocnicy narzędzi CLI: `src/app/api/cli-tools/*` -- Filtr IP: `src/app/api/settings/ip-filter` (GET/PUT) -- Przemyślany budżet: `src/app/api/settings/thinking-budget` (GET/PUT) -- Podpowiedź systemowa: `src/app/api/settings/system-prompt` (GET/PUT) -- Sesje: `src/app/api/sessions` (GET) -- Limity stawek: `src/app/api/rate-limits` (GET) -- Odporność: `src/app/api/resilience` (GET/PATCH) — profile dostawców, wyłącznik automatyczny, stan limitu szybkości -- Reset odporności: `src/app/api/resilience/reset` (POST) - resetuje wyłączniki + czasy odnowienia -- Statystyki pamięci podręcznej: `src/app/api/cache/stats` (GET/DELETE) -- Dostępność modelu: `src/app/api/models/availability` (GET/POST) -- Telemetria: `src/app/api/telemetry/summary` (GET) -- Budżet: `src/app/api/usage/budget` (GET/POST) -- Łańcuchy awaryjne: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Audyt zgodności: `src/app/api/compliance/audit-log` (GET) -- Wartości: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Zasady: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + rdzeń tłumaczeniowy +## 2) SSE + Translation Core -Główne moduły przepływowe: +Main flow modules: -- Wpis: `src/sse/handlers/chat.ts` -- Podstawowa orkiestracja: `open-sse/handlers/chatCore.ts` -- Adaptery wykonawcze dostawcy: `open-sse/executors/*` -- Wykrywanie formatu/konfiguracja dostawcy: `open-sse/services/provider.ts` -- Analiza/rozwiązanie modelu: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Logika zastępcza konta: `open-sse/services/accountFallback.ts` -- Rejestr tłumaczeń: `open-sse/translator/index.ts` -- Transformacje strumieniowe: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Ekstrakcja/normalizacja użycia: `open-sse/utils/usageTracking.ts` -- Pomyśl o parserze tagów: `open-sse/utils/thinkTagParser.ts` -- Obsługa osadzania: `open-sse/handlers/embeddings.ts` -- Rejestr dostawców osadzania: `open-sse/config/embeddingRegistry.ts` -- Obsługa generowania obrazu: `open-sse/handlers/imageGeneration.ts` -- Rejestr dostawców obrazu: `open-sse/config/imageRegistry.ts` -- Odkażanie odpowiedzi: `open-sse/handlers/responseSanitizer.ts` -- Normalizacja ról: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Usługi (logika biznesowa): +Services (business logic): -- Wybór konta/punktacja: `open-sse/services/accountSelector.ts` -- Zarządzanie cyklem życia kontekstu: `open-sse/services/contextManager.ts` -- Wymuszanie filtra IP: `open-sse/services/ipFilter.ts` -- Śledzenie sesji: `open-sse/services/sessionManager.ts` -- Poproś o deduplikację: `open-sse/services/signatureCache.ts` -- Wstrzyknięcie monitu systemowego: `open-sse/services/systemPrompt.ts` -- Myślenie o zarządzaniu budżetem: `open-sse/services/thinkingBudget.ts` -- Routing modelu wieloznacznego: `open-sse/services/wildcardRouter.ts` -- Zarządzanie limitami stawek: `open-sse/services/rateLimitManager.ts` -- Bezpiecznik: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Moduły warstwy domeny: +Domain layer modules: -- Dostępność modelu: `src/lib/domain/modelAvailability.ts` -- Reguły kosztów/budżety: `src/lib/domain/costRules.ts` -- Polityka awaryjna: `src/lib/domain/fallbackPolicy.ts` -- Rozwiązanie kombinacji: `src/lib/domain/comboResolver.ts` -- Polityka blokowania: `src/lib/domain/lockoutPolicy.ts` -- Silnik polityki: `src/domain/policyEngine.ts` — scentralizowana blokada → budżet → ocena rezerwowa -- Katalog kodów błędów: `src/lib/domain/errorCodes.ts` -- Identyfikator żądania: `src/lib/domain/requestId.ts` -- Limit czasu pobierania: `src/lib/domain/fetchTimeout.ts` -- Poproś o telemetrię: `src/lib/domain/requestTelemetry.ts` -- Zgodność/audyt: `src/lib/domain/compliance/index.ts` -- Ewaluacyjny biegacz: `src/lib/domain/evalRunner.ts` -- Trwałość stanu domeny: `src/lib/db/domainState.ts` — SQLite CRUD dla łańcuchów awaryjnych, budżetów, historii kosztów, stanu blokady, wyłączników automatycznych +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Moduły dostawcy OAuth (12 pojedynczych plików pod `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Indeks rejestru: `src/lib/oauth/providers/index.ts` -- Dostawcy indywidualni: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Cienkie opakowanie: `src/lib/oauth/providers.ts` — reeksport z poszczególnych modułów +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Warstwa trwałości +## 3) Persistence Layer -Stan podstawowy DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- plik: `${DATA_DIR}/db.json` (lub `$XDG_CONFIG_HOME/omniroute/db.json`, gdy jest ustawiony, w przeciwnym razie `~/.omniroute/db.json`) -- encje: dostawcaConnections, ProvideNodes, modelAliases, combo, apiKeys, ustawienia, ceny, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Wykorzystanie bazy danych: +Usage persistence: -- `src/lib/usageDb.ts` -- pliki: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- stosuje się do tej samej zasady katalogu podstawowego, co `localDb` (`DATA_DIR`, następnie `XDG_CONFIG_HOME/omniroute`, gdy jest ustawiony) -- rozłożone na skupione podmoduły: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -Baza danych stanu domeny (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — Operacje CRUD dla stanu domeny -- Tabele (utworzone w `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Wzór pamięci podręcznej zapisu: mapy w pamięci są wiarygodne w czasie wykonywania; mutacje są zapisywane synchronicznie do SQLite; stan jest przywracany z bazy danych przy zimnym starcie +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Powierzchnie uwierzytelniające + zabezpieczające +## 4) Auth + Security Surfaces -- Autoryzacja plików cookie w panelu kontrolnym: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Generowanie/weryfikacja klucza API: `src/shared/utils/apiKey.ts` - — Wpisy tajne dostawcy zachowały się we wpisach `providerConnections` -- Obsługa wychodzącego serwera proxy za pośrednictwem `open-sse/utils/proxyFetch.ts` (vars env) i `open-sse/utils/networkProxy.ts` (konfigurowalne dla każdego dostawcy lub globalne) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Synchronizacja z chmurą +## 5) Cloud Sync -- Inicjacja harmonogramu: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Zadanie okresowe: `src/shared/services/cloudSyncScheduler.ts` -- Trasa kontrolna: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Cykl życia żądania (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Kombinacja + przepływ awaryjny konta +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Decyzje awaryjne są podejmowane przez `open-sse/services/accountFallback.ts` przy użyciu kodów stanu i heurystyki komunikatów o błędach. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Cykl życia wdrożenia OAuth i odświeżania tokenu +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Odświeżanie podczas ruchu na żywo jest wykonywane wewnątrz `open-sse/handlers/chatCore.ts` za pośrednictwem modułu wykonującego `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Cykl życia synchronizacji w chmurze (włącz/synchronizuj/wyłącz) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Synchronizacja okresowa jest wyzwalana przez `CloudSyncScheduler`, gdy włączona jest chmura. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Model danych i mapa przechowywania +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Pliki pamięci fizycznej: +Physical storage files: -- stan główny: `${DATA_DIR}/db.json` (lub `$XDG_CONFIG_HOME/omniroute/db.json` gdy jest ustawiony, w przeciwnym wypadku `~/.omniroute/db.json`) -- statystyki użytkowania: `${DATA_DIR}/usage.json` -- linie dziennika żądań: `${DATA_DIR}/log.txt` -- opcjonalne sesje debugowania tłumacza/żądania: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topologia wdrożenia +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Mapowanie modułów (decyzyjne krytyczne) +## Module Mapping (Decision-Critical) -### Moduły tras i API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: interfejsy API zgodności -- `src/app/api/v1/providers/[provider]/*`: dedykowane trasy dla poszczególnych dostawców (czat, osadzanie, obrazy) -- `src/app/api/providers*`: dostawca CRUD, walidacja, testowanie -- `src/app/api/provider-nodes*`: niestandardowe zarządzanie kompatybilnymi węzłami -- `src/app/api/provider-models`: zarządzanie modelami niestandardowymi (CRUD) -- `src/app/api/models/catalog`: API pełnego katalogu modeli (wszystkie typy pogrupowane według dostawcy) -- `src/app/api/oauth/*`: Przepływy OAuth/kodu urządzenia -- `src/app/api/keys*`: cykl życia lokalnego klucza API -- `src/app/api/models/alias`: zarządzanie aliasami -- `src/app/api/combos*`: zarządzanie kombinacjami rezerwowymi -- `src/app/api/pricing`: zastąpienie cen przy kalkulacji kosztów -- `src/app/api/settings/proxy`: konfiguracja proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: test połączenia wychodzącego proxy (POST) -- `src/app/api/usage/*`: interfejsy API użycia i dzienników -- `src/app/api/sync/*` + `src/app/api/cloud/*`: synchronizacja z chmurą i pomocnicy obsługujący chmurę -- `src/app/api/cli-tools/*`: lokalni autorzy/weryfikatorzy konfiguracji CLI -- `src/app/api/settings/ip-filter`: Lista dozwolonych/blokowanych adresów IP (GET/PUT) -- `src/app/api/settings/thinking-budget`: konfiguracja budżetu tokena myślącego (GET/PUT) -- `src/app/api/settings/system-prompt`: globalny monit systemowy (GET/PUT) -- `src/app/api/sessions`: lista aktywnych sesji (GET) -- `src/app/api/rate-limits`: stan limitu stawki za konto (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Rdzeń routingu i wykonania +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: analiza żądań, obsługa kombinacji, pętla wyboru konta -- `open-sse/handlers/chatCore.ts`: tłumaczenie, wysyłanie executora, obsługa ponawiania/odświeżania, konfiguracja strumienia -- `open-sse/executors/*`: zachowanie sieci i formatu specyficzne dla dostawcy +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Rejestr tłumaczeń i konwertery formatów +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: rejestracja i orkiestracja tłumaczy -- Poproś o tłumaczy: `open-sse/translator/request/*` -- Tłumacze odpowiedzi: `open-sse/translator/response/*` -- Stałe formatu: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Trwałość +### Persistence -- `src/lib/localDb.ts`: trwała konfiguracja/stan -- `src/lib/usageDb.ts`: historia użytkowania i logi bieżących żądań +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Zasięg dostawcy-wykonawcy (wzorzec strategii) +## Provider Executor Coverage (Strategy Pattern) -Każdy dostawca ma wyspecjalizowany moduł wykonawczy rozszerzający `BaseExecutor` (w `open-sse/executors/base.ts`), który zapewnia tworzenie adresów URL, konstruowanie nagłówków, ponawianie prób z wykładniczym wycofywaniem, przechwytywanie odświeżania poświadczeń i metodę orkiestracji `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Wykonawca | Dostawca(-y) | Specjalna obsługa | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Razem, Fajerwerki, Cerebras, Cohere, NVIDIA | Dynamiczna konfiguracja adresu URL/nagłówka dla każdego dostawcy | -| `AntigravityExecutor` | Google Antygrawitacja | Niestandardowe identyfikatory projektów/sesji, ponowna próba po przeanalizowaniu | -| `CodexExecutor` | Kodeks OpenAI | Wstrzykuje instrukcje systemowe, wymusza wysiłek rozumowania | -| `CursorExecutor` | Kursor IDE | Protokół ConnectRPC, kodowanie Protobuf, podpisywanie żądań poprzez sumę kontrolną | -| `GithubExecutor` | Drugi pilot GitHuba | Odświeżanie tokenu drugiego pilota, nagłówki naśladujące VSCode | -| `KiroExecutor` | Zaklinacz kodów AWS/Kiro | Format binarny AWS EventStream → Konwersja SSE | -| `GeminiCLIExecutor` | Bliźnięta CLI | Cykl odświeżania tokena Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Wszyscy pozostali dostawcy (w tym niestandardowe kompatybilne węzły) używają `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matryca zgodności dostawców +## Provider Compatibility Matrix -| Dostawca | Formatuj | Autoryzacja | Strumień | Non-Stream | Odświeżenie tokena | Korzystanie z interfejsu API | -| ------------------- | ----------------- | ----------------------------- | ----------------------- | ---------- | ------------------ | ---------------------------- | -| Klaudiusz | klaudia | Klucz API / OAuth | ✅ | ✅ | ✅ | ⚠️ Tylko administrator | -| Bliźnięta | Bliźnięta | Klucz API / OAuth | ✅ | ✅ | ✅ | ⚠️ Konsola chmurowa | -| Bliźnięta CLI | bliźnięta-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Konsola chmurowa | -| Antygrawitacja | antygrawitacja | OAuth | ✅ | ✅ | ✅ | ✅ Pełny limit API | -| OpenAI | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| Kodeks | odpowiedzi openai | OAuth | ✅ zmuszony | ❌ | ✅ | ✅ Limity stawek | -| Drugi pilot GitHuba | otwieram | OAuth + token drugiego pilota | ✅ | ✅ | ✅ | ✅ Migawki kwot | -| Kursor | kursor | Niestandardowa suma kontrolna | ✅ | ✅ | ❌ | ❌ | -| Kiro | Kiro | AWS SSO OIDC | ✅ (Strumień zdarzenia) | ❌ | ✅ | ✅ Limity użytkowania | -| Qwen | otwieram | OAuth | ✅ | ✅ | ✅ | ⚠️ Na żądanie | -| iFlow | otwieram | OAuth (podstawowy) | ✅ | ✅ | ✅ | ⚠️ Na żądanie | -| OtwórzRouter | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | klaudia | Klucz API | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| Groq | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| Mistral | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| Zakłopotanie | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| Razem AI | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| Fajerwerki AI | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| Cerebra | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| Spójne | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | otwieram | Klucz API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Zakres tłumaczenia w formacie +## Format Translation Coverage -Wykryte formaty źródłowe obejmują: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Formaty docelowe obejmują: +Target formats include: -- Czat/odpowiedzi OpenAI -- Klaudiusz -- Koperta Gemini/Gemini-CLI/Antygrawitacyjna +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Kursor +- Cursor -Tłumaczenia używają **OpenAI jako formatu centralnego** — wszystkie konwersje przechodzą przez OpenAI jako pośredni: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Tłumaczenia są wybierane dynamicznie na podstawie kształtu ładunku źródłowego i formatu docelowego dostawcy. +Translations are selected dynamically based on source payload shape and provider target format. -Dodatkowe warstwy przetwarzania w potoku tłumaczenia: +Additional processing layers in the translation pipeline: -- **Oczyszczanie odpowiedzi** — Usuwa niestandardowe pola z odpowiedzi w formacie OpenAI (zarówno przesyłanych strumieniowo, jak i nie przesyłanych strumieniowo), aby zapewnić ścisłą zgodność z SDK -- **Normalizacja ról** — Konwertuje `developer` → `system` dla celów innych niż OpenAI; łączy `system` → `user` dla modeli odrzucających rolę systemową (GLM, ERNIE) -- **Pomyśl o wyodrębnieniu tagów** — Analizuje bloki `...` z treści w polu `reasoning_content` -- **Ustrukturyzowane dane wyjściowe** — Konwertuje OpenAI `response_format.json_schema` na `responseMimeType` Gemini + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Obsługiwane punkty końcowe interfejsu API +## Supported API Endpoints -| Punkt końcowy | Formatuj | Opiekun | -| -------------------------------------------------- | --------------------- | -------------------------------------------------------------- | -| `POST /v1/chat/completions` | Czat OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Wiadomości Claude'a | Ten sam program obsługi (wykryty automatycznie) | -| `POST /v1/responses` | Odpowiedzi OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Osadzania OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Lista modeli | Trasa API | -| `POST /v1/images/generations` | Obrazy OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Lista modeli | Trasa API | -| `POST /v1/providers/{provider}/chat/completions` | Czat OpenAI | Dedykowany dla każdego dostawcy z walidacją modelu | -| `POST /v1/providers/{provider}/embeddings` | Osadzania OpenAI | Dedykowany dla każdego dostawcy z walidacją modelu | -| `POST /v1/providers/{provider}/images/generations` | Obrazy OpenAI | Dedykowany dla każdego dostawcy z walidacją modelu | -| `POST /v1/messages/count_tokens` | Claude Liczba żetonów | Trasa API | -| `GET /v1/models` | Lista modeli OpenAI | Ścieżka API (czat + osadzanie + obraz + modele niestandardowe) | -| `GET /api/models/catalog` | Katalog | Wszystkie modele pogrupowane według dostawcy + typu | -| `POST /v1beta/models/*:streamGenerateContent` | Pochodzący z Bliźniąt | Trasa API | -| `GET/PUT/DELETE /api/settings/proxy` | Konfiguracja proxy | Konfiguracja serwera proxy sieci | -| `POST /api/settings/proxy/test` | Łączność proxy | Punkt końcowy testu kondycji/łączności serwera proxy | -| `GET/POST/DELETE /api/provider-models` | Modele niestandardowe | Zarządzanie modelami niestandardowymi według dostawcy | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Obsługa obejścia +## Bypass Handler -Procedura obsługi obejścia (`open-sse/utils/bypassHandler.ts`) przechwytuje znane żądania „wyrzucenia” z Claude CLI — pingi rozgrzewające, wyodrębnianie tytułów i zliczanie tokenów — i zwraca **fałszywą odpowiedź** bez zużywania tokenów dostawcy nadrzędnego. Jest to wyzwalane tylko wtedy, gdy `User-Agent` zawiera `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Potok żądania rejestratora +## Request Logger Pipeline -Rejestrator żądań (`open-sse/utils/requestLogger.ts`) zapewnia 7-etapowy potok rejestrowania debugowania, domyślnie wyłączony, włączony poprzez `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Pliki są zapisywane w `/logs//` dla każdej sesji żądań. +Files are written to `/logs//` for each request session. -## Tryby awarii i odporność +## Failure Modes and Resilience -## 1) Dostępność konta/dostawcy +## 1) Account/Provider Availability -- czas oczekiwania na konto dostawcy w przypadku błędów przejściowych/szybkości/auth -- rezerwowe konto przed nieudanym żądaniem -- powrót do modelu kombi, gdy bieżąca ścieżka modelu/dostawcy zostanie wyczerpana +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Wygaśnięcie tokena +## 2) Token Expiry -- wstępne sprawdzenie i odświeżenie z ponowną próbą dla dostawców z możliwością odświeżania -- Ponowna próba 401/403 po próbie odświeżenia w ścieżce podstawowej +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Bezpieczeństwo transmisji +## 3) Stream Safety -- kontroler strumienia obsługujący rozłączenie -- strumień tłumaczeń z opróżnianiem na końcu strumienia i obsługą `[DONE]` -- rezerwowe oszacowanie użycia w przypadku braku metadanych dotyczących użycia dostawcy +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Degradacja synchronizacji w chmurze +## 4) Cloud Sync Degradation -- pojawiają się błędy synchronizacji, ale lokalne środowisko wykonawcze trwa -- harmonogram ma logikę umożliwiającą ponawianie prób, ale wykonywanie okresowe obecnie domyślnie wywołuje synchronizację przy pojedynczej próbie +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integralność danych +## 5) Data Integrity -- Migracja/naprawa kształtu DB w przypadku brakujących kluczy -- uszkodzone zabezpieczenia resetowania JSON dla localDb i useDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Obserwowalność i sygnały operacyjne +## Observability and Operational Signals -Źródła widoczności w czasie wykonywania: +Runtime visibility sources: -- logi konsoli z `src/sse/utils/logger.ts` -- agregacje użycia na żądanie w `usage.json` -- logowanie o status żądania tekstowego `log.txt` -- opcjonalne głębokie dzienniki żądań/tłumaczeń pod `logs/`, gdy `ENABLE_REQUEST_LOGS=true` -- punkty końcowe użycia panelu kontrolnego (`/api/usage/*`) do wykorzystania interfejsu użytkownika +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Granice wrażliwe na bezpieczeństwo +## Security-Sensitive Boundaries -- Sekret JWT (`JWT_SECRET`) zabezpiecza weryfikację/podpisywanie plików cookie sesji panelu kontrolnego - — Początkowe hasło zastępcze (`INITIAL_PASSWORD`, domyślne `123456`) musi zostać zastąpione w rzeczywistych wdrożeniach -- Klucz API Sekret HMAC (`API_KEY_SECRET`) zabezpiecza wygenerowany lokalny format klucza API -- Sekrety dostawcy (klucze/tokeny API) są zachowywane w lokalnej bazie danych i powinny być chronione na poziomie systemu plików -- Punkty końcowe synchronizacji w chmurze opierają się na uwierzytelnianiu klucza API + semantyce identyfikatora komputera +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Środowisko i macierz czasu wykonywania +## Environment and Runtime Matrix -Zmienne środowiskowe aktywnie używane przez kod: +Environment variables actively used by code: -- Aplikacja/autoryzacja: `JWT_SECRET`, `INITIAL_PASSWORD` -- Przechowywanie: `DATA_DIR` -- Zgodne zachowanie węzła: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Opcjonalne obejście bazy pamięci (Linux/macOS, gdy `DATA_DIR` nie jest ustawione): `XDG_CONFIG_HOME` -- Haszowanie zabezpieczeń: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Logowanie: `ENABLE_REQUEST_LOGS` -- Adres URL synchronizacji/chmury: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Wychodzące proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` i warianty pisane małymi literami -- flagi funkcji SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Pomocnicy platformy/środowiska wykonawczego (konfiguracja nie specyficzna dla aplikacji): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Znane uwagi architektoniczne +## Known Architectural Notes -1. `usageDb` i `localDb` mają teraz tę samą podstawową politykę katalogową (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) z migracją starszych plików. -2. `/api/v1/route.ts` zwraca statyczną listę modeli i nie jest głównym źródłem modeli używanym przez `/v1/models`. -3. Rejestrator żądań zapisuje pełne nagłówki/treść, gdy jest włączony; traktuj katalog dzienników jako poufny. -4. Zachowanie chmury zależy od prawidłowego `NEXT_PUBLIC_BASE_URL` i osiągalności punktu końcowego chmury. -5. Katalog `open-sse/` jest publikowany jako `@omniroute/open-sse` **pakiet obszaru roboczego npm**. Kod źródłowy importuje go poprzez `@omniroute/open-sse/...` (rozwiązany przez Next.js `transpilePackages`). Aby zachować spójność, ścieżki plików w tym dokumencie nadal używają nazwy katalogu `open-sse/`. -6. Wykresy na pulpicie nawigacyjnym korzystają z **Recharts** (oparte na SVG) w celu uzyskania przystępnych, interaktywnych wizualizacji analitycznych (wykresy słupkowe wykorzystania modelu, tabele podziału dostawców ze wskaźnikami sukcesu). -7. Testy E2E wykorzystują **Playwright** (`tests/e2e/`), uruchamiają się przez `npm run test:e2e`. Testy jednostkowe korzystają z **programu uruchamiającego testy Node.js** (`tests/unit/`), uruchamianego za pośrednictwem `npm run test:plan3`. Kod źródłowy pod `src/` to **TypeScript** (`.ts`/`.tsx`); obszarem roboczym `open-sse/` pozostaje JavaScript (`.js`). -8. Strona ustawień jest podzielona na 5 zakładek: Bezpieczeństwo, Routing (6 globalnych strategii: najpierw wypełnij, okrężnie, p2c, losowa, najrzadziej używana, zoptymalizowana pod względem kosztów), Odporność (edytowalne limity szybkości, wyłącznik automatyczny, zasady), AI (przemyślany budżet, monit systemowy, pamięć podręczna podpowiedzi), Zaawansowane (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Lista kontrolna weryfikacji operacyjnej +## Operational Verification Checklist -- Kompiluj ze źródła: `npm run build` -- Zbuduj obraz Dockera: `docker build -t omniroute .` -- Uruchom usługę i sprawdź: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- Podstawowy docelowy adres URL CLI powinien mieć postać `http://:20128/v1`, gdy `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/pl/CODEBASE_DOCUMENTATION.md b/docs/i18n/pl/CODEBASE_DOCUMENTATION.md index 72c7ddfb6d..303880c198 100644 --- a/docs/i18n/pl/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/pl/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — dokumentacja bazy kodu +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Obszerny, przyjazny dla początkujących przewodnik po routerze proxy AI **omniroute** obsługującym wielu dostawców. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Co to jest omniroute? +## 1. What Is omniroute? -omniroute to **router proxy**, który znajduje się pomiędzy klientami AI (Claude CLI, Codex, Cursor IDE itp.) a dostawcami AI (Anthropic, Google, OpenAI, AWS, GitHub itp.). Rozwiązuje jeden duży problem: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Różni klienci AI mówią różnymi „językami” (formatami API), a różni dostawcy AI również oczekują różnych „języków”.** omniroute dokonuje automatycznego tłumaczenia między nimi. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Pomyśl o tym jak o uniwersalnym tłumaczu w Organizacji Narodów Zjednoczonych — każdy delegat może mówić w dowolnym języku, a tłumacz konwertuje go na dowolnego innego delegata. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Przegląd architektury +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Podstawowa zasada: tłumaczenie typu Hub-and-Spoke +### Core Principle: Hub-and-Spoke Translation -Tłumaczenie wszystkich formatów przechodzi przez **format OpenAI jako centrum**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Oznacza to, że potrzebujesz tylko **N tłumaczy** (po jednym na format) zamiast **N²** (każda para). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Struktura projektu +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Podział modułów na moduły +## 4. Module-by-Module Breakdown -### Konfiguracja 4.1 (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**Pojedyncze źródło prawdy** dla wszystkich konfiguracji dostawców. +The **single source of truth** for all provider configuration. -| Plik | Cel | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | Obiekt `PROVIDERS` z podstawowymi adresami URL, poświadczeniami OAuth (domyślne), nagłówkami i domyślnymi monitami systemowymi dla każdego dostawcy. Definiuje również `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` i `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Ładuje zewnętrzne poświadczenia z `data/provider-credentials.json` i łączy je z zakodowanymi na stałe wartościami domyślnymi w `PROVIDERS`. Chroni tajemnice przed kontrolą źródła, zachowując jednocześnie kompatybilność wsteczną. | -| `providerModels.ts` | Centralny rejestr modeli: aliasy dostawców map → identyfikatory modeli. Funkcje takie jak `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Instrukcje systemowe wstrzykiwane do żądań Kodeksu (ograniczenia edycyjne, reguły piaskownicy, zasady zatwierdzania). | -| `defaultThinkingSignature.ts` | Domyślne sygnatury „myślące” dla modeli Claude i Gemini. | -| `ollamaModels.ts` | Definicja schematu dla lokalnych modeli Ollama (nazwa, rozmiar, rodzina, kwantyzacja). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Proces ładowania danych uwierzytelniających +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Executory (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Wykonawcy hermetyzują **logikę specyficzną dla dostawcy** przy użyciu **wzorca strategii**. Każdy wykonawca w razie potrzeby zastępuje metody podstawowe. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Wykonawca | Dostawca | Kluczowe specjalizacje | -| ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Baza abstrakcyjna: budowanie adresów URL, nagłówki, logika ponownych prób, odświeżanie danych logowania | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Ogólne odświeżanie tokena OAuth dla standardowych dostawców | -| `antigravity.ts` | Kod Google Cloud | Generowanie identyfikatora projektu/sesji, rezerwowy adres wielu adresów URL, niestandardowa analiza ponownych prób na podstawie komunikatów o błędach („reset po 2h7m23s”) | -| `cursor.ts` | Kursor IDE | **Najbardziej złożone**: uwierzytelnianie sumy kontrolnej SHA-256, kodowanie żądania Protobuf, binarny EventStream → parsowanie odpowiedzi SSE | -| `codex.ts` | Kodeks OpenAI | Wstrzykuje instrukcje systemowe, zarządza poziomami myślenia, usuwa nieobsługiwane parametry | -| `gemini-cli.ts` | Interfejs wiersza polecenia Google Gemini | Tworzenie niestandardowego adresu URL (`streamGenerateContent`), odświeżanie tokena Google OAuth | -| `github.ts` | Drugi pilot GitHuba | System podwójnego tokena (GitHub OAuth + token Copilot), naśladowanie nagłówka VSCode | -| `kiro.ts` | Zaklinacz kodów AWS | Parsowanie binarne AWS EventStream, ramki zdarzeń AMZN, szacowanie tokenów | -| `index.ts` | — | Fabryka: nazwa dostawcy map → klasa wykonawcy, z domyślnym rezerwowym | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Programy obsługi (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**Warstwa orkiestracji** — koordynuje tłumaczenie, wykonywanie, przesyłanie strumieniowe i obsługę błędów. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Plik | Cel | -| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Centralny orkiestrator** (~600 linii). Obsługuje pełny cykl życia żądania: wykrywanie formatu → tłumaczenie → wysyłanie modułu wykonawczego → odpowiedź przesyłana strumieniowo/nie przesyłana strumieniowo → odświeżanie tokena → obsługa błędów → rejestrowanie użycia. | -| `responsesHandler.ts` | Adapter dla API OpenAI Responses: konwertuje format Responses → Ukończenia czatu → wysyła do `chatCore` → konwertuje SSE z powrotem do formatu Responses. | -| `embeddings.ts` | Procedura obsługi generowania osadzania: rozwiązuje model osadzania → dostawca, wysyła do interfejsu API dostawcy, zwraca odpowiedź na osadzanie zgodną z OpenAI. Obsługuje ponad 6 dostawców. | -| `imageGeneration.ts` | Moduł obsługi generowania obrazu: rozpoznaje model obrazu → dostawca, obsługuje tryby zgodne z OpenAI, obraz Gemini (antygrawitacja) i tryb awaryjny (Nebius). Zwraca obrazy base64 lub URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Cykl życia żądania (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Usługi (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Logika biznesowa obsługująca procedury obsługi i wykonawców. +Business logic that supports the handlers and executors. -| Plik | Cel | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Wykrywanie formatu** (`detectFormat`): analizuje strukturę treści żądania w celu identyfikacji formatów Claude/OpenAI/Gemini/Antigravity/Responses (w tym heurystyka `max_tokens` dla Claude). Ponadto: budowanie adresów URL, budowanie nagłówków, normalizacja konfiguracji myślenia. Obsługuje dostawców dynamicznych `openai-compatible-*` i `anthropic-compatible-*`. | -| `model.ts` | Analiza ciągów modelu (`claude/model-name` → `{provider: "claude", model: "model-name"}`), rozpoznawanie aliasów z wykrywaniem kolizji, oczyszczanie danych wejściowych (odrzuca przejście ścieżki/znaki sterujące) i rozpoznawanie informacji o modelu z obsługą asynchronicznego modułu pobierającego aliasy. | -| `accountFallback.ts` | Obsługa limitów szybkości: wykładniczy wycofywanie (1 s → 2 s → 4 s → maksymalnie 2 minuty), zarządzanie czasem odnowienia konta, klasyfikacja błędów (które błędy powodują awarię, a które nie). | -| `tokenRefresh.ts` | Odświeżenie tokena OAuth dla **każdego dostawcy**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (podwójny token OAuth + Copilot), Kiro (AWS SSO OIDC + Social Auth). Zawiera pamięć podręczną deduplikacji obiecującą w locie i ponawianie prób z wykładniczym wycofywaniem. | -| `combo.ts` | **Modele kombinowane**: łańcuchy modeli awaryjnych. Jeśli model A zawiedzie z powodu błędu kwalifikującego się do powrotu, wypróbuj model B, następnie C itd. Zwraca rzeczywiste kody stanu nadrzędnego. | -| `usage.ts` | Pobiera dane o przydziałach/wykorzystaniu z interfejsów API dostawców (przydziały GitHub Copilot, przydziały modelu antygrawitacyjnego, limity szybkości Kodeksu, zestawienia użycia Kiro, ustawienia Claude). | -| `accountSelector.ts` | Inteligentny wybór konta za pomocą algorytmu punktacji: uwzględnia priorytet, stan zdrowia, pozycję w trybie okrężnym i stan odnowienia, aby wybrać optymalne konto dla każdego żądania. | -| `contextManager.ts` | Zarządzanie cyklem życia kontekstu żądania: tworzy i śledzi obiekty kontekstu na żądanie z metadanymi (identyfikator żądania, znaczniki czasu, informacje o dostawcy) na potrzeby debugowania i rejestrowania. | -| `ipFilter.ts` | Kontrola dostępu oparta na protokole IP: obsługuje tryby listy dozwolonych i list zablokowanych. Przed przetworzeniem żądań API sprawdza adres IP klienta pod kątem skonfigurowanych reguł. | -| `sessionManager.ts` | Śledzenie sesji za pomocą odcisku palca klienta: śledzi aktywne sesje przy użyciu zaszyfrowanych identyfikatorów klienta, monitoruje liczbę żądań i zapewnia metryki sesji. | -| `signatureCache.ts` | Pamięć podręczna deduplikacji oparta na sygnaturach żądań: zapobiega duplikowaniu żądań poprzez buforowanie ostatnich podpisów żądań i zwracanie buforowanych odpowiedzi na identyczne żądania w określonym przedziale czasowym. | -| `systemPrompt.ts` | Globalne wprowadzenie monitu systemowego: dołącza konfigurowalny monit systemowy do wszystkich żądań, z obsługą zgodności dla poszczególnych dostawców. | -| `thinkingBudget.ts` | Zarządzanie budżetem tokenów wnioskowania: obsługuje tryby przekazywania, automatyczne (konfiguracja myślenia paskowego), niestandardowe (stały budżet) i tryby adaptacyjne (skalowane złożoności) do kontrolowania tokenów myślenia/wnioskowania. | -| `wildcardRouter.ts` | Routing wzorców modelu z symbolami wieloznacznymi: rozwiązuje wzorce z symbolami wieloznacznymi (np. `*/claude-*`) do konkretnych par dostawca/model w oparciu o dostępność i priorytet. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Deduplikacja odświeżania tokenu +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Zastępcza maszyna stanu konta +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Łańcuch modeli Combo +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### Tłumacz 4.5 (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**Silnik tłumaczenia formatów** wykorzystujący system samorejestrujących się wtyczek. +The **format translation engine** using a self-registering plugin system. -#### Architektura +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Katalog | Pliki | Opis | -| ------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 tłumaczy | Konwertuj treści żądań między formatami. Każdy plik rejestruje się automatycznie poprzez `register(from, to, fn)` podczas importu. | -| `response/` | 7 tłumaczy | Konwertuj fragmenty odpowiedzi przesyłanych strumieniowo między formatami. Obsługuje typy zdarzeń SSE, bloki myślowe, wywołania narzędzi. | -| `helpers/` | 6 pomocników | Wspólne narzędzia: `claudeHelper` (ekstrakcja podpowiedzi systemowych, konfiguracja myślenia), `geminiHelper` (mapowanie części/zawartości), `openaiHelper` (filtrowanie formatu), `toolCallHelper` (generowanie identyfikatora, wstrzykiwanie brakującej odpowiedzi), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Silnik tłumaczeniowy: `translateRequest()`, `translateResponse()`, zarządzanie państwem, rejestr. | -| `formats.ts` | — | Stałe formatu: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Projekt klucza: wtyczki samorejestrujące +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Narzędzia (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Plik | Cel | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Tworzenie reakcji na błędy (format zgodny z OpenAI), analizowanie błędów w górę, ekstrakcja czasu ponownej próby antygrawitacyjnej z komunikatów o błędach, przesyłanie strumieniowe błędów SSE. | -| `stream.ts` | **SSE Transform Stream** — główny potok przesyłania strumieniowego. Dwa tryby: `TRANSLATE` (tłumaczenie w pełnym formacie) i `PASSTHROUGH` (normalizacja + użycie ekstraktu). Obsługuje buforowanie fragmentów, szacowanie użycia, śledzenie długości treści. Instancje kodera/dekodera na strumień unikają stanu współdzielonego. | -| `streamHelpers.ts` | Narzędzia SSE niskiego poziomu: `parseSSELine` (tolerancja białych znaków), `hasValuableContent` (filtruje puste fragmenty dla OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serializacja SSE z uwzględnieniem formatu z czyszczeniem `perf_metrics`). | -| `usageTracking.ts` | Ekstrakcja użycia tokena z dowolnego formatu (Claude/OpenAI/Gemini/Responses), szacowanie za pomocą oddzielnych współczynników znaków na token narzędzia/wiadomości, dodanie bufora (margines bezpieczeństwa 2000 tokenów), filtrowanie pól specyficzne dla formatu, rejestrowanie konsoli za pomocą kolorów ANSI. | -| `requestLogger.ts` | Rejestrowanie żądań w oparciu o pliki (opcja poprzez `ENABLE_REQUEST_LOGS=true`). Tworzy foldery sesji z ponumerowanymi plikami: `1_req_client.json` → `7_res_client.txt`. Wszystkie wejścia/wyjścia są asynchroniczne (odpal i zapomnij). Maskuje wrażliwe nagłówki. | -| `bypassHandler.ts` | Przechwytuje określone wzorce z Claude CLI (wyodrębnianie tytułu, rozgrzewka, liczenie) i zwraca fałszywe odpowiedzi bez wywoływania żadnego dostawcy. Obsługuje zarówno przesyłanie strumieniowe, jak i inne. Celowo ograniczone do zakresu Claude CLI. | -| `networkProxy.ts` | Rozwiązuje wychodzący adres URL proxy dla danego dostawcy z pierwszeństwem: konfiguracja specyficzna dla dostawcy → konfiguracja globalna → zmienne środowiskowe (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Obsługuje wyjątki `NO_PROXY`. Buforuje konfigurację przez 30 sekund. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Rurociąg przesyłania strumieniowego SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Struktura sesji rejestratora żądania +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Warstwa aplikacji (`src/`) +### 4.7 Application Layer (`src/`) -| Katalog | Cel | -| ------------- | -------------------------------------------------------------------------------------------------------------- | -| `src/app/` | Interfejs sieciowy, trasy API, oprogramowanie pośredniczące Express, procedury obsługi wywołań zwrotnych OAuth | -| `src/lib/` | Dostęp do bazy danych (`localDb.ts`, `usageDb.ts`), uwierzytelnianie, współdzielone | -| `src/mitm/` | Narzędzia proxy typu „man-in-the-middle” do przechwytywania ruchu dostawcy | -| `src/models/` | Definicje modeli baz danych | -| `src/shared/` | Opakowania wokół funkcji open-sse (dostawca, strumień, błąd itp.) | -| `src/sse/` | Procedury obsługi punktów końcowych SSE, które łączą bibliotekę open-sse z trasami Express | -| `src/store/` | Zarządzanie stanem aplikacji | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Godne uwagi trasy API +#### Notable API Routes -| Trasa | Metody | Cel | -| --------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | POBIERZ/POST/USUŃ | CRUD dla niestandardowych modeli na dostawcę | -| `/api/models/catalog` | OTRZYMAJ | Zagregowany katalog wszystkich modeli (czat, osadzanie, obraz, niestandardowy) pogrupowany według dostawcy | -| `/api/settings/proxy` | POBIERZ/PUT/USUŃ | Hierarchiczna konfiguracja wychodzącego proxy (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Sprawdza łączność proxy i zwraca publiczny adres IP/opóźnienie | -| `/v1/providers/[provider]/chat/completions` | POST | Dedykowane uzupełnianie czatów dla poszczególnych dostawców z walidacją modelu | -| `/v1/providers/[provider]/embeddings` | POST | Dedykowane osadzanie dla poszczególnych dostawców z walidacją modelu | -| `/v1/providers/[provider]/images/generations` | POST | Dedykowane generowanie obrazów dla poszczególnych dostawców z walidacją modelu | -| `/api/settings/ip-filter` | POBIERZ/WSTAW | Zarządzanie listą dozwolonych/blokowanych adresów IP | -| `/api/settings/thinking-budget` | POBIERZ/WSTAW | Konfiguracja budżetu tokena rozumowania (przejściowa/automatyczna/niestandardowa/adaptacyjna) | -| `/api/settings/system-prompt` | POBIERZ/WSTAW | Globalny systemowy zastrzyk monitu dla wszystkich żądań | -| `/api/sessions` | OTRZYMAJ | Śledzenie i metryki aktywnych sesji | -| `/api/rate-limits` | OTRZYMAJ | Stan limitu stawek za konto | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Kluczowe wzorce projektowe +## 5. Key Design Patterns -### 5.1 Tłumaczenie typu Hub-and-Spoke +### 5.1 Hub-and-Spoke Translation -Wszystkie formaty są tłumaczone poprzez **format OpenAI jako centrum**. Dodanie nowego dostawcy wymaga jedynie napisania **jednej pary** tłumaczy (do/z OpenAI), a nie N par. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Wzorzec strategii wykonawcy +### 5.2 Executor Strategy Pattern -Każdy dostawca ma dedykowaną klasę wykonawczą dziedziczącą z `BaseExecutor`. Fabryka w `executors/index.ts` wybiera właściwą w czasie wykonywania. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 System wtyczek samorejestrujących +### 5.3 Self-Registering Plugin System -Moduły tłumacza rejestrują się przy imporcie poprzez `register()`. Dodanie nowego tłumacza polega po prostu na utworzeniu pliku i zaimportowaniu go. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Zwrot konta z wykładniczym wycofywaniem +### 5.4 Account Fallback with Exponential Backoff -Kiedy dostawca zwróci 429/401/500, system może przełączyć się na następne konto, stosując wykładnicze czasy odnowienia (1 s → 2 s → 4 s → maksymalnie 2 minuty). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### Łańcuchy modeli Combo 5.5 +### 5.5 Combo Model Chains -„Kombinacja” grupuje wiele ciągów `provider/model`. Jeśli pierwszy się nie powiedzie, automatycznie wróć do następnego. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Stanowe tłumaczenie strumieniowe +### 5.6 Stateful Streaming Translation -Tłumaczenie odpowiedzi utrzymuje stan we wszystkich fragmentach SSE (śledzenie bloków myślenia, gromadzenie wywołań narzędzi, indeksowanie bloków treści) za pośrednictwem mechanizmu `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Bufor bezpieczeństwa użytkowania +### 5.7 Usage Safety Buffer -Do raportowanego użycia dodawany jest bufor o pojemności 2000 tokenów, aby zapobiec przekraczaniu przez klientów limitów okna kontekstowego z powodu narzutu wynikającego z monitów systemowych i translacji formatów. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Obsługiwane formaty +## 6. Supported Formats -| Formatuj | Kierunek | Identyfikator | -| ----------------------------------------- | ------------ | ------------------ | -| Ukończenie czatu OpenAI | źródło + cel | `openai` | -| API odpowiedzi OpenAI | źródło + cel | `openai-responses` | -| Antropiczny Claude | źródło + cel | `claude` | -| Google Bliźnięta | źródło + cel | `gemini` | -| Interfejs wiersza polecenia Google Gemini | tylko cel | `gemini-cli` | -| Antygrawitacja | źródło + cel | `antigravity` | -| AWS Kiro | tylko cel | `kiro` | -| Kursor | tylko cel | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Obsługiwani dostawcy +## 7. Supported Providers -| Dostawca | Metoda autoryzacji | Wykonawca | Kluczowe notatki | -| ----------------------------------------- | -------------------------------- | -------------- | ------------------------------------------------------------------------ | -| Antropiczny Claude | Klucz API lub OAuth | Domyślne | Używa nagłówka `x-api-key` | -| Google Bliźnięta | Klucz API lub OAuth | Domyślne | Używa nagłówka `x-goog-api-key` | -| Interfejs wiersza polecenia Google Gemini | OAuth | BliźniętaCLI | Używa punktu końcowego `streamGenerateContent` | -| Antygrawitacja | OAuth | Antygrawitacja | Zastępczy adres wielu adresów URL, niestandardowa analiza ponownych prób | -| OpenAI | Klucz API | Domyślne | Autoryzacja okaziciela standardowego | -| Kodeks | OAuth | Kodeks | Wstrzykuje instrukcje systemowe, zarządza myśleniem | -| Drugi pilot GitHuba | OAuth + token drugiego pilota | GitHuba | Podwójny token, nagłówek VSCode naśladujący | -| Kiro (AWS) | AWS SSO OIDC lub społecznościowe | Kiro | Analiza binarnego strumienia zdarzeń | -| Kursor IDE | Autoryzacja sumy kontrolnej | Kursor | Kodowanie Protobuf, sumy kontrolne SHA-256 | -| Qwen | OAuth | Domyślne | Autoryzacja standardowa | -| iFlow | OAuth (podstawowy + nośnik) | Domyślne | Nagłówek podwójnego uwierzytelniania | -| OtwórzRouter | Klucz API | Domyślne | Autoryzacja okaziciela standardowego | -| GLM, Kimi, MiniMax | Klucz API | Domyślne | Kompatybilny z Claude, użyj `x-api-key` | -| `openai-compatible-*` | Klucz API | Domyślne | Dynamiczny: dowolny punkt końcowy zgodny z OpenAI | -| `anthropic-compatible-*` | Klucz API | Domyślne | Dynamiczny: dowolny punkt końcowy zgodny z Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Podsumowanie przepływu danych +## 8. Data Flow Summary -### Żądanie transmisji strumieniowej +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Żądanie bez przesyłania strumieniowego +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Przepływ obejściowy (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/pl/FEATURES.md b/docs/i18n/pl/FEATURES.md index 7df6e316a8..82cc73b67b 100644 --- a/docs/i18n/pl/FEATURES.md +++ b/docs/i18n/pl/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Galeria funkcji panelu kontrolnego +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Wizualny przewodnik po każdej sekcji pulpitu nawigacyjnego OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Dostawcy +## 🔌 Providers -Zarządzaj połączeniami dostawców AI: dostawcy OAuth (Claude Code, Codex, Gemini CLI), dostawcy kluczy API (Groq, DeepSeek, OpenRouter) i dostawcy usług bezpłatnych (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Kombinacje +## 🎨 Combos -Twórz kombinacje routing (model aliases, background task degradation)u modeli za pomocą 6 strategii: najpierw wypełnij, okrężnie, siła dwóch wyborów, losowa, najrzadziej używana i zoptymalizowana pod względem kosztów. Każda kombinacja łączy wiele modeli z automatycznym cofaniem. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Analityka +## 📊 Analytics -Kompleksowa analiza użytkowania obejmująca zużycie tokenów, szacunki kosztów, mapy cieplne aktywności, tygodniowe wykresy dystrybucji i zestawienia poszczególnych dostawców. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Stan systemu +## 🏥 System Health -Monitorowanie w czasie rzeczywistym: czas pracy, pamięć, wersja, percentyle opóźnień (p50/p95/p99), statystyki pamięci podręcznej i stany wyłączników automatycznych dostawcy. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Plac zabaw dla tłumaczy +## 🔧 Translator Playground -Cztery tryby debugowania tłumaczeń API: **Playground** (konwerter formatów), **Chat Tester** (żądania na żywo), **Test Bench** (testy wsadowe) i **Live Monitor** (strumień w czasie rzeczywistym). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Ustawienia +## 🎮 Model Playground _(v2.0.9+)_ -Ustawienia ogólne, pamięć systemowa, zarządzanie kopiami zapasowymi (baza danych eksportu/importu), wygląd (tryb ciemny/jasny), bezpieczeństwo (w tym ochrona punktu końcowego API i niestandardowe blokowanie dostawców), routing, odporność i zaawansowana konfiguracja. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Narzędzia CLI +## 🔧 CLI Tools -Konfiguracja jednym kliknięciem narzędzi do kodowania AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code i Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Poproś o dzienniki +## 🤖 CLI Agents _(v2.0.11+)_ -Rejestrowanie żądań w czasie rzeczywistym z filtrowaniem według dostawcy, modelu, konta i klucza API. Pokazuje kody stanu, użycie tokenu, opóźnienie i szczegóły odpowiedzi. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Punkt końcowy interfejsu API +## 🌐 API Endpoint -Twój ujednolicony punkt końcowy API z podziałem możliwości: uzupełnianie czatu, osadzanie, generowanie obrazu, zmiana rankingu, transkrypcja audio i zarejestrowane klucze API. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/pl/TROUBLESHOOTING.md b/docs/i18n/pl/TROUBLESHOOTING.md index 4e981f7f31..120092d63c 100644 --- a/docs/i18n/pl/TROUBLESHOOTING.md +++ b/docs/i18n/pl/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Rozwiązywanie problemów +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Typowe problemy i rozwiązania dla OmniRoute. +Common problems and solutions for OmniRoute. --- -## Szybkie poprawki +## Quick Fixes -| Problem | Rozwiązanie | -| ------------------------------------------ | -------------------------------------------------------------------------------------- | -| Pierwsze logowanie nie działa | Sprawdź `INITIAL_PASSWORD` w `.env` (domyślnie: `123456`) | -| Panel kontrolny otwiera się na złym porcie | Ustaw `PORT=20128` i `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Brak dzienników żądań pod `logs/` | Ustaw `ENABLE_REQUEST_LOGS=true` | -| EACCES: odmowa pozwolenia | Ustaw `DATA_DIR=/path/to/writable/dir`, aby zastąpić `~/.omniroute` | -| Strategia routingu nie jest zapisywana | Aktualizacja do wersji 1.4.11+ (poprawka schematu Zoda zapewniająca trwałość ustawień) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Problemy z dostawcą +## Provider Issues -### „Model językowy nie dostarczał komunikatów” +### "Language model did not provide messages" -**Przyczyna:** Limit dostawcy został wyczerpany. +**Cause:** Provider quota exhausted. -**Poprawka:** +**Fix:** -1. Sprawdź moduł śledzenia limitów na pulpicie nawigacyjnym -2. Użyj kombinacji z poziomami rezerwowymi -3. Przejdź na tańszy/bezpłatny poziom +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Ograniczanie szybkości +### Rate Limiting -**Przyczyna:** Wyczerpany limit subskrypcji. +**Cause:** Subscription quota exhausted. -**Poprawka:** +**Fix:** -- Dodaj rezerwę: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Użyj GLM/MiniMax jako taniej kopii zapasowej +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Token OAuth wygasł +### OAuth Token Expired -OmniRoute automatycznie odświeża tokeny. Jeśli problemy nadal występują: +OmniRoute auto-refreshes tokens. If issues persist: -1. Panel kontrolny → Dostawca → Połącz ponownie -2. Usuń i ponownie dodaj połączenie dostawcy +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Problemy z chmurą +## Cloud Issues -### Błędy synchronizacji z chmurą +### Cloud Sync Errors -1. Sprawdź, czy `BASE_URL` wskazuje na działającą instancję (np. `http://localhost:20128`) -2. Zweryfikuj punkty `CLOUD_URL` w punkcie końcowym w chmurze (np. `https://omniroute.dev`) -3. Zachowaj wyrównanie wartości `NEXT_PUBLIC_*` z wartościami po stronie serwera +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Chmura `stream=false` Zwraca 500 +### Cloud `stream=false` Returns 500 -**Objaw:** `Unexpected token 'd'...` na punkcie końcowym w chmurze dla połączeń innych niż przesyłanie strumieniowe. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Przyczyna:** Upstream zwraca ładunek SSE, podczas gdy klient oczekuje JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Rozwiązanie:** użyj `stream=true` do bezpośrednich połączeń w chmurze. Lokalne środowisko wykonawcze obejmuje rezerwę SSE → JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud wyświetla komunikat „Połączono”, ale „nieprawidłowy klucz API” +### Cloud Says Connected but "Invalid API key" -1. Utwórz nowy klucz z lokalnego pulpitu nawigacyjnego (`/api/keys`) -2. Uruchom synchronizację z chmurą: Włącz chmurę → Synchronizuj teraz -3. Stare/niezsynchronizowane klucze nadal mogą zwracać `401` w chmurze +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Problemy z Dockerem +## Docker Issues -### Narzędzie CLI pokazuje, że nie jest zainstalowane +### CLI Tool Shows Not Installed -1. Sprawdź pola wykonawcze: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. W trybie przenośnym: użyj docelowego obrazu `runner-cli` (w pakiecie CLI) -3. W trybie montowania hosta: ustaw `CLI_EXTRA_PATHS` i zamontuj katalog bin hosta jako tylko do odczytu -4. Jeśli `installed=true` i `runnable=false`: znaleziono plik binarny, ale kontrola stanu nie powiodła się +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Szybka weryfikacja środowiska wykonawczego +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Problemy z kosztami +## Cost Issues -### Wysokie koszty +### High Costs -1. Sprawdź statystyki użytkowania w Panelu → Użycie -2. Zmień model podstawowy na GLM/MiniMax -3. Korzystaj z bezpłatnej warstwy (Gemini CLI, iFlow) do zadań niekrytycznych -4. Ustaw budżety kosztów według klucza API: Panel → Klucze API → Budżet +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Debugowanie +## Debugging -### Włącz dzienniki żądań +### Enable Request Logs -Ustaw `ENABLE_REQUEST_LOGS=true` w swoim pliku `.env`. Dzienniki pojawiają się w katalogu `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Sprawdź stan dostawcy +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Pamięć uruchomieniowa +### Runtime Storage -- Stan główny: `${DATA_DIR}/db.json` (dostawcy, kombinacje, aliasy, klucze, ustawienia) -- Użycie: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Dzienniki żądań: `/logs/...` (kiedy `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Problemy z wyłącznikami automatycznymi +## Circuit Breaker Issues -### Dostawca utknął w stanie OTWARTYM +### Provider stuck in OPEN state -Gdy wyłącznik automatyczny dostawcy jest OTWARTY, żądania są blokowane do czasu upłynięcia czasu odnowienia. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Poprawka:** +**Fix:** -1. Przejdź do **Panel sterowania → Ustawienia → Odporność** -2. Sprawdź kartę wyłącznika dla odpowiedniego dostawcy -3. Kliknij **Resetuj wszystko**, aby wyczyścić wszystkie wyłączniki, lub poczekaj, aż upłynie czas odnowienia -4. Przed zresetowaniem sprawdź, czy dostawca jest rzeczywiście dostępny +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Dostawca ciągle uruchamia wyłącznik automatyczny +### Provider keeps tripping the circuit breaker -Jeśli dostawca wielokrotnie wchodzi w stan OPEN: +If a provider repeatedly enters OPEN state: -1. Sprawdź **Panel kontrolny → Kondycja → Kondycja dostawcy** pod kątem wzorca awarii -2. Przejdź do **Ustawienia → Odporność → Profile dostawców** i zwiększ próg awarii -3. Sprawdź, czy dostawca zmienił limity API lub wymaga ponownego uwierzytelnienia -4. Sprawdź dane telemetryczne dotyczące opóźnień — duże opóźnienia mogą powodować awarie wynikające z przekroczenia limitu czasu +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problemy z transkrypcją dźwięku +## Audio Transcription Issues -### Błąd „Nieobsługiwany model”. +### "Unsupported model" error -- Upewnij się, że używasz prawidłowego przedrostka: `deepgram/nova-3` lub `assemblyai/best` -- Sprawdź, czy dostawca jest podłączony w ** Panelu → Dostawcy** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Transkrypcja zwraca wartość pustą lub kończy się niepowodzeniem +### Transcription returns empty or fails -- Sprawdź obsługiwane formaty audio: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Sprawdź, czy rozmiar pliku mieści się w granicach dostawcy (zwykle < 25 MB) -- Sprawdź ważność klucza API dostawcy na karcie dostawcy +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Debugowanie tłumacza +## Translator Debugging -Użyj **Panel kontrolny → Tłumacz**, aby debugować problemy z tłumaczeniem formatu: +Use **Dashboard → Translator** to debug format translation issues: -| Tryb | Kiedy stosować | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| **Plac zabaw** | Porównaj formaty wejścia/wyjścia obok siebie — wklej nieudane żądanie, aby zobaczyć, jak zostanie przetłumaczone | -| **Tester czatu** | Wysyłaj wiadomości na żywo i sprawdzaj pełny ładunek żądania/odpowiedzi, w tym nagłówki | -| **Stolik testowy** | Przeprowadź testy wsadowe dla kombinacji formatów, aby dowiedzieć się, które tłumaczenia są uszkodzone | -| **Monitorowanie na żywo** | Obserwuj przepływ żądań w czasie rzeczywistym, aby wykryć sporadyczne problemy z tłumaczeniem | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Typowe problemy z formatem +### Common format issues -- **Tagi myślenia nie pojawiają się** — Sprawdź, czy dostawca docelowy obsługuje myślenie i ustawienie budżetu na myślenie -- **Porzucanie wywołań narzędzi** — Niektóre tłumaczenia formatów mogą usuwać nieobsługiwane pola; sprawdź w trybie placu zabaw -- **Brak podpowiedzi systemowej** — Claude i Gemini inaczej obsługują podpowiedzi systemowe; sprawdź wynik tłumaczenia -- **SDK zwraca surowy ciąg znaków zamiast obiektu** — Naprawiono w wersji 1.1.0: narzędzie do czyszczenia odpowiedzi usuwa teraz niestandardowe pola (`x_groq`, `usage_breakdown` itp.), które powodują błędy sprawdzania poprawności OpenAI SDK w Pydantic -- **GLM/ERNIE odrzuca rolę `system`** — Naprawiono w wersji 1.1.0: normalizator ról automatycznie łączy komunikaty systemowe z komunikatami użytkownika w przypadku niekompatybilnych modeli -- **`developer` rola nie została rozpoznana** — Naprawiono w wersji 1.1.0: automatycznie konwertowana na `system` dla dostawców innych niż OpenAI -- **`json_schema` nie działa z Gemini** — Naprawiono w wersji 1.1.0: `response_format` jest teraz konwertowany na `responseMimeType` Gemini + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Ustawienia odporności +## Resilience Settings -### Automatyczny limit szybkości nie uruchamia się +### Auto rate-limit not triggering -- Automatyczne ograniczenie szybkości dotyczy tylko dostawców kluczy API (nie OAuth/subskrypcja) -- Sprawdź, czy **Ustawienia → Odporność → Profile dostawców** ma włączone automatyczne ograniczenie stawek -- Sprawdź, czy dostawca zwraca kody stanu `429` lub nagłówki `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Dostrajanie wykładniczego wycofywania +### Tuning exponential backoff -Profile dostawców obsługują następujące ustawienia: +Provider profiles support these settings: -- **Opóźnienie bazowe** — Początkowy czas oczekiwania po pierwszej awarii (domyślnie: 1 s) -- **Maks. opóźnienie** — Maksymalny limit czasu oczekiwania (domyślnie: 30 s) -- **Mnożnik** — O ile zwiększyć opóźnienie przy kolejnej awarii (domyślnie: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Stado przeciw grzmotom +### Anti-thundering herd -Gdy wiele jednoczesnych żądań trafia do dostawcy z ograniczoną szybkością, OmniRoute używa mutexu i automatycznego ograniczania szybkości, aby serializować żądania i zapobiegać kaskadowym błędom. Jest to automatyczne w przypadku dostawców kluczy API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Nadal utknąłeś? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Problemy z GitHubem**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architektura**: Zobacz [link](ARCHITECTURE.md), aby uzyskać szczegółowe informacje wewnętrzne -- **Dokumentacja API**: Zobacz [link](API_REFERENCE.md) dla wszystkich punktów końcowych -- **Panel stanu**: Sprawdź **Panel kontrolny → Zdrowie**, aby sprawdzić stan systemu w czasie rzeczywistym -- **Tłumacz**: Użyj **Panel kontrolny → Tłumacz**, aby debugować problemy z formatem +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/pl/USER_GUIDE.md b/docs/i18n/pl/USER_GUIDE.md index 578f504150..5a043224df 100644 --- a/docs/i18n/pl/USER_GUIDE.md +++ b/docs/i18n/pl/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Podręcznik użytkownika +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Kompletny przewodnik dotyczący konfigurowania dostawców, tworzenia kombinacji, integracji narzędzi CLI i wdrażania OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Spis treści +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Kompletny przewodnik dotyczący konfigurowania dostawców, tworzenia kombinacji, --- -## 💰 Ceny w skrócie +## 💰 Pricing at a Glance -| Poziom | Dostawca | Koszt | Reset przydziału | Najlepsze dla | -| ------------------ | ------------------- | ----------------- | ----------------------------- | ------------------------- | -| **💳 SUBSKRYPCJA** | Claude Code (Pro) | 20 USD/mies. | 5h + tygodniowo | Już subskrybujesz | -| | Kodeks (Plus/Pro) | 20-200 $/mies. | 5h + tygodniowo | Użytkownicy OpenAI | -| | Bliźnięta CLI | **BEZPŁATNE** | 180 tys./mies. + 1 tys./dzień | Wszyscy! | -| | Drugi pilot GitHuba | 10–19 USD/mies. | Miesięczne | Użytkownicy GitHuba | -| **🔑 KLUCZ API** | DeepSeek | Płać za użycie | Brak | Tanie rozumowanie | -| | Groq | Płać za użycie | Brak | Ultraszybkie wnioskowanie | -| | xAI (Grok) | Płać za użycie | Brak | Grok 4 rozumowanie | -| | Mistral | Płać za użycie | Brak | Modele hostowane w UE | -| | Zakłopotanie | Płać za użycie | Brak | Rozszerzone wyszukiwanie | -| | Razem AI | Płać za użycie | Brak | Modele open source | -| | Fajerwerki AI | Płać za użycie | Brak | Obrazy Fast FLUX | -| | Cerebra | Płać za użycie | Brak | Prędkość w skali opłatka | -| | Spójne | Płać za użycie | Brak | Polecenie R+RAG | -| | NVIDIA NIM | Płać za użycie | Brak | Modele korporacyjne | -| **💰 TANIO** | GLM-4.7 | 0,6 USD/1 mln | Codziennie 10:00 | Kopia zapasowa budżetu | -| | MiniMax M2.1 | 0,2 USD/1 mln | 5-godzinne toczenie | Najtańsza opcja | -| | Kimi K2 | 9 USD miesięcznie | 10 mln tokenów/mies. | Przewidywalny koszt | -| **🆓 DARMOWE** | iFlow | 0 dolarów | Nieograniczony | 8 modeli za darmo | -| | Qwen | 0 dolarów | Nieograniczony | 3 modele za darmo | -| | Kiro | 0 dolarów | Nieograniczony | Claude wolny | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Wskazówka dla profesjonalistów:** Zacznij od zestawu Gemini CLI (180 tys. za darmo/miesiąc) + iFlow (bez ograniczeń za darmo) = koszt 0 USD! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Przypadki użycia +## 🎯 Use Cases -### Przypadek 1: „Mam subskrypcję Claude Pro” +### Case 1: "I have Claude Pro subscription" -**Problem:** Limit wygasa niewykorzystany, limity szybkości podczas intensywnego kodowania +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Przypadek 2: „Chcę zerowych kosztów” +### Case 2: "I want zero cost" -**Problem:** Nie stać Cię na subskrypcje, potrzebujesz niezawodnego kodowania AI +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Przypadek 3: „Potrzebuję kodowania 24 godziny na dobę, 7 dni w tygodniu, bez przerw” +### Case 3: "I need 24/7 coding, no interruptions" -**Problem:** Terminy, nie mogę sobie pozwolić na przestoje +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Przypadek 4: „Chcę DARMOWEJ sztucznej inteligencji w OpenClaw” +### Case 4: "I want FREE AI in OpenClaw" -**Problem:** Potrzebujesz asystenta AI w aplikacjach do przesyłania wiadomości, całkowicie za darmo +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Konfiguracja dostawcy +## 📖 Provider Setup -### 🔐 Dostawcy subskrypcji +### 🔐 Subscription Providers -#### Kod Claude’a (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Wskazówka dla profesjonalistów:** używaj Opus do skomplikowanych zadań, a Sonnet do szybkości. OmniRoute śledzi limit na model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### Kodeks OpenAI (Plus/Pro) +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (DARMOWE 180 tys./miesiąc!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Najlepsza wartość:** Ogromny darmowy poziom! Użyj tego przed płatnymi poziomami. +**Best Value:** Huge free tier! Use this before paid tiers. -#### Drugi pilot GitHuba +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Tani dostawcy +### 💰 Cheap Providers -#### GLM-4.7 (reset dzienny, 0,6 USD/1 mln) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Zarejestruj się: [Zhipu AI](https://open.bigmodel.cn/) -2. Uzyskaj klucz API z planu kodowania -3. Panel → Dodaj klucz API: Dostawca: `glm`, Klucz API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Zastosuj:** `glm/glm-4.7` — **Wskazówka dla profesjonalistów:** Plan kodowania oferuje 3× limit przy cenie 1/7! Resetuj codziennie o 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (reset 5 godz., 0,20 USD/1 mln) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Zarejestruj się: [MiniMax](https://www.minimax.io/) -2. Uzyskaj klucz API → Panel kontrolny → Dodaj klucz API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Użyj:** `minimax/MiniMax-M2.1` — **Wskazówka:** Najtańsza opcja dla długiego kontekstu (1 mln tokenów)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (9 USD miesięcznie) +#### Kimi K2 ($9/month flat) -1. Subskrybuj: [Moonshot AI](https://platform.moonshot.ai/) -2. Uzyskaj klucz API → Panel kontrolny → Dodaj klucz API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Zastosowanie:** `kimi/kimi-latest` — **Wskazówka dla profesjonalistów:** Stałe 9 USD/miesiąc za 10 mln tokenów = efektywny koszt 0,90 USD/1 mln! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 DARMOWE Dostawcy +### 🆓 FREE Providers -#### iFlow (8 DARMOWYCH modeli) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 DARMOWE modele) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude ZA DARMO) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Kombinacje +## 🎨 Combos -### Przykład 1: Maksymalizuj subskrypcję → Tania kopia zapasowa +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Przykład 2: Tylko bezpłatny (zero kosztów) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 Integracja z CLI +## 🔧 CLI Integration -### IDE kursora +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Kod Claude’a +### Claude Code -Edytuj `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Edytuj `~/.claude/config.json`: } ``` -### Interfejs wiersza polecenia Kodeksu +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Edytuj `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Edytuj `~/.openclaw/openclaw.json`: } ``` -**Lub użyj Dashboardu:** Narzędzia CLI → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Kliknij / Kontynuuj / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Wdrożenie +## 🚀 Deployment -### Wdrożenie VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### Doker +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Informacje na temat trybu zintegrowanego z hostem i plików binarnych CLI można znaleźć w sekcji Docker w głównych dokumentach. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Zmienne środowiskowe +### Environment Variables -| Zmienna | Domyślne | Opis | -| --------------------- | ------------------------------------ | ----------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Tajemnica podpisania JWT (**zmiana w produkcji**) | -| `INITIAL_PASSWORD` | `123456` | Hasło pierwszego logowania | -| `DATA_DIR` | `~/.omniroute` | Katalog danych (db, wykorzystanie, logi) | -| `PORT` | domyślne ramy | Port serwisowy (w przykładach `20128`) | -| `HOSTNAME` | domyślne ramy | Powiąż hosta (domyślnie Docker to `0.0.0.0`) | -| `NODE_ENV` | domyślne środowisko wykonawcze | Ustaw `production` dla wdrożenia | -| `BASE_URL` | `http://localhost:20128` | Wewnętrzny podstawowy adres URL po stronie serwera | -| `CLOUD_URL` | `https://omniroute.dev` | Podstawowy adres URL punktu końcowego synchronizacji w chmurze | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Sekret HMAC dla wygenerowanych kluczy API | -| `REQUIRE_API_KEY` | `false` | Wymuś klucz API nośnika na `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Włącza dzienniki żądań/odpowiedzi | -| `AUTH_COOKIE_SECURE` | `false` | Wymuś plik cookie uwierzytelniający `Secure` (za odwrotnym proxy HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Aby zapoznać się z pełnym odwołaniem do zmiennej środowiskowej, zobacz [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Dostępne modele +## 📊 Available Models
-Wyświetl wszystkie dostępne modele +View all available models -**Kod Claude (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Kodeks (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — BEZPŁATNE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Kopilot GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — 0,6 USD/1 mln: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — 0,2 USD/1 mln: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — BEZPŁATNIE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — BEZPŁATNIE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — ZA DARMO: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,15 +460,15 @@ Aby zapoznać się z pełnym odwołaniem do zmiennej środowiskowej, zobacz [REA **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Zakłopotanie (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Wspólna AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -** Sztuczna inteligencja fajerwerków (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Mózgi (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Spójność (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Aby zapoznać się z pełnym odwołaniem do zmiennej środowiskowej, zobacz [REA --- -## 🧩 Zaawansowane funkcje +## 🧩 Advanced Features -### Modele niestandardowe +### Custom Models -Dodaj dowolny identyfikator modelu do dowolnego dostawcy, nie czekając na aktualizację aplikacji: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Lub użyj Panelu: **Dostawcy → [Dostawca] → Modele niestandardowe**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Dedykowane trasy dostawców +### Dedicated Provider Routes -Kieruj żądania bezpośrednio do konkretnego dostawcy z walidacją modelu: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Prefiks dostawcy jest dodawany automatycznie, jeśli go brakuje. Niedopasowane modele zwracają `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Konfiguracja serwera proxy sieci +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Pierwszeństwo:** specyficzne dla klucza → specyficzne dla kombinacji → specyficzne dla dostawcy → globalne → środowisko. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API katalogu modeli +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Zwraca modele pogrupowane według dostawcy z typami (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Synchronizacja z chmurą +### Cloud Sync -- Synchronizuj dostawców, kombinacje i ustawienia na różnych urządzeniach -- Automatyczna synchronizacja w tle z limitem czasu + szybka awaria -- Preferuj po stronie serwera `BASE_URL`/`CLOUD_URL` w produkcji +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### Inteligencja bramy LLM (faza 9) +### LLM Gateway Intelligence (Phase 9) -- **Semantyczna pamięć podręczna** — automatycznie buforuje dane niestrumieniowe, temperatura = 0 odpowiedzi (pomiń za pomocą `X-OmniRoute-No-Cache: true`) -- **Idempotencja żądania** — Deduplikuje żądania w ciągu 5 sekund za pośrednictwem nagłówka `Idempotency-Key` lub `X-Request-Id` -- **Śledzenie postępu** — Zgoda na zdarzenia SSE `event: progress` poprzez nagłówek `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Plac zabaw dla tłumaczy +### Translator Playground -Dostęp przez **Panel kontrolny → Tłumacz**. Debuguj i wizualizuj, jak OmniRoute tłumaczy żądania API między dostawcami. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Tryb | Cel | -| ------------------------- | --------------------------------------------------------------------------------------------------- | -| **Plac zabaw** | Wybierz formaty źródłowe/docelowe, wklej żądanie i natychmiast zobacz przetłumaczone dane wyjściowe | -| **Tester czatu** | Wysyłaj wiadomości na czacie na żywo przez serwer proxy i sprawdzaj pełny cykl żądań/odpowiedzi | -| **Stolik testowy** | Przeprowadź testy wsadowe w wielu kombinacjach formatów, aby sprawdzić poprawność tłumaczenia | -| **Monitorowanie na żywo** | Oglądaj tłumaczenia w czasie rzeczywistym, gdy żądania przepływają przez serwer proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Przypadki użycia:** +**Use cases:** -- Debugowanie, dlaczego konkretna kombinacja klient/dostawca nie działa -- Sprawdź, czy znaczniki myślenia, wywołania narzędzi i podpowiedzi systemowe są tłumaczone poprawnie -- Porównaj różnice w formatach między formatami OpenAI, Claude, Gemini i Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Strategie routingu +### Routing Strategies -Skonfiguruj za pomocą **Panel kontrolny → Ustawienia → Routing**. +Configure via **Dashboard → Settings → Routing**. -| Strategia | Opis | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | -| **Najpierw wypełnij** | Używa kont w kolejności priorytetów — konto podstawowe obsługuje wszystkie żądania, aż będą niedostępne | -| **Robinowy** | Przełącza między wszystkimi kontami z konfigurowalnym limitem stałym (domyślnie: 3 połączenia na konto) | -| **P2C (potęga dwóch wyborów)** | Wybiera 2 losowe konta i ścieżki do zdrowszego — równoważy obciążenie świadomością zdrowia | -| **Losowe** | Losowo wybiera konto dla każdego żądania, korzystając z funkcji losowania Fisher-Yates | -| **Najrzadziej używane** | Kieruje do konta z najstarszym `lastUsedAt` znacznikiem czasu, równomiernie rozprowadzając ruch | -| **Optymalizacja kosztów** | Kieruje do konta o najniższej wartości priorytetu, optymalizując pod kątem dostawców o najniższych kosztach | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Aliasy modeli z symbolami wieloznacznymi +#### Wildcard Model Aliases -Utwórz wzorce symboli wieloznacznych, aby ponownie przypisać nazwy modeli: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Symbole wieloznaczne obsługują `*` (dowolne znaki) i `?` (pojedynczy znak). +Wildcards support `*` (any characters) and `?` (single character). -#### Łańcuchy awaryjne +#### Fallback Chains -Zdefiniuj globalne łańcuchy awaryjne, które mają zastosowanie do wszystkich żądań: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Odporność i wyłączniki automatyczne +### Resilience & Circuit Breakers -Skonfiguruj za pomocą **Panel kontrolny → Ustawienia → Odporność**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute wdraża odporność na poziomie dostawcy za pomocą czterech komponentów: +OmniRoute implements provider-level resilience with four components: -1. **Profile dostawców** — konfiguracja dla poszczególnych dostawców dla: - - Próg awaryjności (ile awarii przed otwarciem) - - Czas odnowienia - - Czułość wykrywania limitu szybkości - - Wykładnicze parametry wycofywania +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Edytowalne limity prędkości** — Domyślne ustawienia na poziomie systemu można skonfigurować w panelu kontrolnym: - - **Żądania na minutę (RPM)** — Maksymalna liczba żądań na minutę na konto - - **Min. czas między żądaniami** — Minimalna przerwa w milisekundach między żądaniami - - **Maksymalna liczba jednoczesnych żądań** — Maksymalna liczba jednoczesnych żądań na konto - - Kliknij **Edytuj**, aby zmodyfikować, a następnie **Zapisz** lub **Anuluj**. Wartości są zachowywane za pośrednictwem interfejsu API odporności. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Wyłącznik** — śledzi awarie według dostawcy i automatycznie otwiera obwód po osiągnięciu progu: - - **ZAMKNIĘTE** (zdrowe) — Żądania przebiegają normalnie - - **OTWARTE** — Dostawca jest tymczasowo blokowany po powtarzających się awariach - - **HALF_OPEN** — Sprawdzanie, czy dostawca odzyskał siły +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Zasady i zablokowane identyfikatory** — Pokazuje stan wyłącznika automatycznego i zablokowane identyfikatory z możliwością wymuszonego odblokowania. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Automatyczne wykrywanie limitów szybkości** — Monitoruje nagłówki `429` i `Retry-After`, aby aktywnie zapobiegać przekroczeniu limitów stawek dostawcy. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Wskazówka dla profesjonalistów:** Użyj przycisku **Resetuj wszystko**, aby wyczyścić wszystkie wyłączniki automatyczne i czasy odnowienia, gdy dostawca wznowi działanie po awarii. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Eksport/import bazy danych +### Database Export / Import -Zarządzaj kopiami zapasowymi baz danych w **Panel kontrolny → Ustawienia → System i pamięć masowa**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Akcja | Opis | -| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Eksportuj bazę danych** | Pobiera bieżącą bazę danych SQLite jako plik `.sqlite` | -| **Eksportuj wszystko (.tar.gz)** | Pobiera pełne archiwum kopii zapasowych, w tym: bazę danych, ustawienia, kombinacje, połączenia z dostawcami (bez poświadczeń), metadane klucza API | -| **Importuj bazę danych** | Prześlij plik `.sqlite`, aby zastąpić bieżącą bazę danych. Automatycznie tworzona jest kopia zapasowa przed importem | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Weryfikacja importu:** Zaimportowany plik jest sprawdzany pod kątem integralności (sprawdzanie pragma SQLite), wymaganych tabel (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) i rozmiaru (maks. 100MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Przypadki użycia:** +**Use Cases:** -- Przeprowadź migrację OmniRoute pomiędzy maszynami -- Twórz zewnętrzne kopie zapasowe w celu odzyskiwania po awarii -- Udostępniaj konfiguracje pomiędzy członkami zespołu (eksportuj wszystko → udostępnij archiwum) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Panel ustawień +### Settings Dashboard -Strona ustawień jest podzielona na 5 zakładek ułatwiających nawigację: +The settings page is organized into 5 tabs for easy navigation: -| Zakładka | Spis treści | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | -| **Bezpieczeństwo** | Ustawienia logowania/hasła, kontrola dostępu IP, autoryzacja API dla `/models` i blokowanie dostawców | -| **Trasowanie** | Globalna strategia routingu (6 opcji), aliasy modeli z symbolami wieloznacznymi, łańcuchy awaryjne, domyślne kombinacje | -| **Odporność** | Profile dostawców, edytowalne limity stawek, stan wyłącznika, zasady i zablokowane identyfikatory | -| **AI** | Myślenie o konfiguracji budżetu, globalnym wstrzykiwaniu podpowiedzi do systemu, szybkich statystykach pamięci podręcznej | -| **Zaawansowane** | Globalna konfiguracja proxy (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Zarządzanie kosztami i budżetem +### Costs & Budget Management -Dostęp przez **Panel kontrolny → Koszty**. +Access via **Dashboard → Costs**. -| Zakładka | Cel | -| ---------- | --------------------------------------------------------------------------------------------------------------------- | -| **Budżet** | Ustaw limity wydatków na klucz API z budżetami dziennymi/tygodniowymi/miesięcznymi i śledzeniem w czasie rzeczywistym | -| **Cennik** | Wyświetlaj i edytuj wpisy cen modelu — koszt za 1 tys. tokenów wejścia/wyjścia na dostawcę | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Śledzenie kosztów:** Każde żądanie rejestruje użycie tokena i oblicza koszt, korzystając z tabeli cen. Zobacz zestawienia w **Panel kontrolny → Użycie** według dostawcy, modelu i klucza API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Transkrypcja audio +### Audio Transcription -OmniRoute obsługuje transkrypcję audio za pośrednictwem punktu końcowego kompatybilnego z OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Dostępni dostawcy: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Obsługiwane formaty audio: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Strategie równoważenia kombinacji +### Combo Balancing Strategies -Skonfiguruj równoważenie poszczególnych kombinacji w **Panel sterowania → Kombinacje → Utwórz/edytuj → Strategia**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategia | Opis | -| ------------------------- | --------------------------------------------------------------------------------- | -| **Równy z każdym** | Obraca modele sekwencyjnie | -| **Priorytet** | Zawsze wypróbowuje pierwszy model; powraca tylko w przypadku błędu | -| **Losowe** | Wybiera losowy model z kombinacji dla każdego żądania | -| **Ważona** | Trasy proporcjonalnie na podstawie przypisanych wag do modelu | -| **Najrzadziej używane** | Trasy do modelu z najmniejszą liczbą ostatnich żądań (wykorzystuje metryki kombi) | -| **Optymalizacja kosztów** | Trasy do najtańszego dostępnego modelu (korzysta z tabeli cen) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Globalne ustawienia domyślne kombinacji można ustawić w **Panel sterowania → Ustawienia → Routing → Domyślne ustawienia kombinacji**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Panel zdrowia +### Health Dashboard -Dostęp przez **Panel kontrolny → Zdrowie**. Przegląd stanu systemu w czasie rzeczywistym za pomocą 6 kart: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Karta | Co to pokazuje | -| ----------------------------- | --------------------------------------------------------------------------------- | -| **Stan systemu** | Czas pracy, wersja, wykorzystanie pamięci, katalog danych | -| **Zdrowie dostawcy** | Stan wyłącznika automatycznego dostawcy (zamknięty/otwarty/półotwarty) | -| **Limity stawek** | Aktywne czasy odnowienia limitu szybkości na konto z pozostałym czasem | -| **Aktywne blokady** | Dostawcy tymczasowo zablokowani przez politykę blokad | -| **Pamięć podręczna podpisów** | Statystyki pamięci podręcznej deduplikacji (aktywne klucze, współczynnik trafień) | -| **Telemetria opóźnień** | Agregacja opóźnień p50/p95/p99 na dostawcę | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Wskazówka dla profesjonalistów:** Strona Zdrowie odświeża się automatycznie co 10 sekund. Użyj karty wyłącznika, aby zidentyfikować dostawców, u których występują problemy. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/pt-BR/API_REFERENCE.md b/docs/i18n/pt-BR/API_REFERENCE.md index 2c0ae042a1..b795722c11 100644 --- a/docs/i18n/pt-BR/API_REFERENCE.md +++ b/docs/i18n/pt-BR/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Referência de API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Referência completa para todos os endpoints da API OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Índice +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Referência completa para todos os endpoints da API OmniRoute. --- -## Conclusões de bate-papo +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Cabeçalhos personalizados +### Custom Headers -| Cabeçalho | Direção | Descrição | -| ------------------------ | ----------- | ---------------------------------------------------------- | -| `X-OmniRoute-No-Cache` | Solicitação | Defina como `true` para ignorar o cache | -| `X-OmniRoute-Progress` | Solicitação | Defina como `true` para eventos de progresso | -| `Idempotency-Key` | Solicitação | Chave de desduplicação (janela 5s) | -| `X-Request-Id` | Solicitação | Chave de desduplicação alternativa | -| `X-OmniRoute-Cache` | Resposta | `HIT` ou `MISS` (sem streaming) | -| `X-OmniRoute-Idempotent` | Resposta | `true` se desduplicado | -| `X-OmniRoute-Progress` | Resposta | `enabled` se o acompanhamento do progresso estiver ativado | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Incorporações +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Provedores disponíveis: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Geração de imagem +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Provedores disponíveis: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Listar modelos +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Terminais de compatibilidade +## Compatibility Endpoints -| Método | Caminho | Formato | -| ------ | --------------------------- | -------------------- | -| POSTAR | `/v1/chat/completions` | OpenAI | -| POSTAR | `/v1/messages` | Antrópico | -| POSTAR | `/v1/responses` | Respostas OpenAI | -| POSTAR | `/v1/embeddings` | OpenAI | -| POSTAR | `/v1/images/generations` | OpenAI | -| OBTER | `/v1/models` | OpenAI | -| POSTAR | `/v1/messages/count_tokens` | Antrópico | -| OBTER | `/v1beta/models` | Gêmeos | -| POSTAR | `/v1beta/models/{...path}` | Gêmeos gera conteúdo | -| POSTAR | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Rotas de provedores dedicados +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -O prefixo do provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Cache Semântico +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Exemplo de resposta: +Response example: ```json { @@ -162,154 +162,164 @@ Exemplo de resposta: --- -## Painel e gerenciamento +## Dashboard & Management -### Autenticação +### Authentication -| Ponto final | Método | Descrição | -| ----------------------------- | ------------- | ------------------------- | -| `/api/auth/login` | POSTAR | Entrar | -| `/api/auth/logout` | POSTAR | Sair | -| `/api/settings/require-login` | OBTER/COLOCAR | Alternar login necessário | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Gerenciamento de Provedores +### Provider Management -| Ponto final | Método | Descrição | -| ---------------------------- | --------------------- | -------------------------------- | -| `/api/providers` | OBTER/POSTAR | Listar/criar provedores | -| `/api/providers/[id]` | OBTER/COLOCAR/EXCLUIR | Gerenciar um provedor | -| `/api/providers/[id]/test` | POSTAR | Testar conexão do provedor | -| `/api/providers/[id]/models` | OBTER | Listar modelos de provedores | -| `/api/providers/validate` | POSTAR | Validar configuração do provedor | -| `/api/provider-nodes*` | Vários | Gerenciamento de nós de provedor | -| `/api/provider-models` | OBTER/POSTAR/EXCLUIR | Modelos personalizados | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Fluxos OAuth +### OAuth Flows -| Ponto final | Método | Descrição | -| -------------------------------- | ------ | ---------------------------- | -| `/api/oauth/[provider]/[action]` | Vários | OAuth específico do provedor | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Roteamento e configuração +### Routing & Config -| Ponto final | Método | Descrição | -| --------------------- | ------------ | -------------------------------------- | -| `/api/models/alias` | OBTER/POSTAR | Aliases de modelo | -| `/api/models/catalog` | OBTER | Todos os modelos por fornecedor + tipo | -| `/api/combos*` | Vários | Gestão de combos | -| `/api/keys*` | Vários | Gerenciamento de chaves API | -| `/api/pricing` | OBTER | Preços do modelo | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Uso e análise +### Usage & Analytics -| Ponto final | Método | Descrição | -| --------------------------- | ------ | ---------------------------- | -| `/api/usage/history` | OBTER | Histórico de uso | -| `/api/usage/logs` | OBTER | Registros de uso | -| `/api/usage/request-logs` | OBTER | Logs em nível de solicitação | -| `/api/usage/[connectionId]` | OBTER | Uso por conexão | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Configurações +### Settings -| Ponto final | Método | Descrição | -| ------------------------------- | ------------- | -------------------------------------------- | -| `/api/settings` | OBTER/COLOCAR | Configurações gerais | -| `/api/settings/proxy` | OBTER/COLOCAR | Configuração de proxy de rede | -| `/api/settings/proxy/test` | POSTAR | Testar conexão proxy | -| `/api/settings/ip-filter` | OBTER/COLOCAR | Lista de permissões/lista de bloqueios de IP | -| `/api/settings/thinking-budget` | OBTER/COLOCAR | Orçamento de token de raciocínio | -| `/api/settings/system-prompt` | OBTER/COLOCAR | Alerta do sistema global | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Monitoramento +### Monitoring -| Ponto final | Método | Descrição | -| ------------------------ | ------------- | ------------------------------ | -| `/api/sessions` | OBTER | Acompanhamento de sessão ativa | -| `/api/rate-limits` | OBTER | Limites de taxas por conta | -| `/api/monitoring/health` | OBTER | Exame de saúde | -| `/api/cache` | OBTER/EXCLUIR | Estatísticas de cache/limpar | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Backup e exportação/importação +### Backup & Export/Import -| Ponto final | Método | Descrição | -| --------------------------- | ------- | ------------------------------------------------------- | -| `/api/db-backups` | OBTER | Listar backups disponíveis | -| `/api/db-backups` | COLOCAR | Crie um backup manual | -| `/api/db-backups` | POSTAR | Restaurar de um backup específico | -| `/api/db-backups/export` | OBTER | Baixe o banco de dados como arquivo .sqlite | -| `/api/db-backups/import` | POSTAR | Carregar arquivo .sqlite para substituir banco de dados | -| `/api/db-backups/exportAll` | OBTER | Baixe o backup completo como arquivo .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Sincronização na nuvem +### Cloud Sync -| Ponto final | Método | Descrição | -| ---------------------- | ------ | ----------------------------------- | -| `/api/sync/cloud` | Vários | Operações de sincronização em nuvem | -| `/api/sync/initialize` | POSTAR | Inicializar sincronização | -| `/api/cloud/*` | Vários | Gerenciamento de nuvem | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Ferramentas CLI +### CLI Tools -| Ponto final | Método | Descrição | -| ---------------------------------- | ------ | ------------------------------ | -| `/api/cli-tools/claude-settings` | OBTER | Status CLI de Claude | -| `/api/cli-tools/codex-settings` | OBTER | Status da CLI do Codex | -| `/api/cli-tools/droid-settings` | OBTER | Status da CLI do Droid | -| `/api/cli-tools/openclaw-settings` | OBTER | Status da CLI do OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | OBTER | Tempo de execução CLI genérico | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -As respostas CLI incluem: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Resiliência e limites de taxas +### ACP Agents -| Ponto final | Método | Descrição | -| ----------------------- | ------------- | ------------------------------------- | -| `/api/resilience` | OBTER/COLOCAR | Obter/atualizar perfis de resiliência | -| `/api/resilience/reset` | POSTAR | Reinicializar disjuntores | -| `/api/rate-limits` | OBTER | Status do limite de taxa por conta | -| `/api/rate-limit` | OBTER | Configuração de limite de taxa global | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Avaliações +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Ponto final | Método | Descrição | -| ------------ | ------------ | --------------------------------------------- | -| `/api/evals` | OBTER/POSTAR | Listar suítes de avaliação/executar avaliação | +### Resilience & Rate Limits -### Políticas +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Ponto final | Método | Descrição | -| --------------- | -------------------- | --------------------------------- | -| `/api/policies` | OBTER/POSTAR/EXCLUIR | Gerenciar políticas de roteamento | +### Evals -### Conformidade +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Ponto final | Método | Descrição | -| --------------------------- | ------ | ----------------------------------------------- | -| `/api/compliance/audit-log` | OBTER | Registo de auditoria de conformidade (último N) | +### Policies -### v1beta (compatível com Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Ponto final | Método | Descrição | -| -------------------------- | ------ | --------------------------------------------- | -| `/v1beta/models` | OBTER | Listar modelos no formato Gemini | -| `/v1beta/models/{...path}` | POSTAR | Ponto de extremidade Gêmeos `generateContent` | +### Compliance -Esses endpoints refletem o formato API do Gemini para clientes que esperam compatibilidade nativa do Gemini SDK. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### APIs internas/do sistema +### v1beta (Gemini-Compatible) -| Ponto final | Método | Descrição | -| --------------- | ------ | ----------------------------------------------------------------------- | -| `/api/init` | OBTER | Verificação de inicialização do aplicativo (usada na primeira execução) | -| `/api/tags` | OBTER | Tags de modelo compatíveis com Ollama (para clientes Ollama) | -| `/api/restart` | POSTAR | Acionar reinicialização normal do servidor | -| `/api/shutdown` | POSTAR | Acionar o desligamento normal do servidor | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Observação:** Esses endpoints são usados internamente pelo sistema ou para compatibilidade do cliente Ollama. Eles normalmente não são chamados pelos usuários finais. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Transcrição de áudio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transcreva arquivos de áudio usando Deepgram ou AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Solicitação:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Resposta:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Provedores suportados:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Formatos suportados:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Compatibilidade com Ollama +## Ollama Compatibility -Para clientes que usam o formato API do Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -As solicitações são traduzidas automaticamente entre o Ollama e os formatos internos. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetria +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Resposta:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Orçamento +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Disponibilidade do modelo +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Processamento de solicitação +## Request Processing -1. Cliente envia solicitação para `/v1/*` -2. O manipulador de rota chama `handleChat`, `handleEmbedding`, `handleAudioTranscription` ou `handleImageGeneration` -3. O modelo foi resolvido (provedor/modelo direto ou alias/combo) -4. Credenciais selecionadas do banco de dados local com filtragem de disponibilidade de conta -5. Para bate-papo: `handleChatCore` — detecção de formato, tradução, verificação de cache, verificação de idempotência -6. O executor do provedor envia uma solicitação upstream -7. Resposta traduzida de volta para o formato do cliente (chat) ou retornada como está (incorporações/imagens/áudio) -8. Uso/registro registrado -9. Fallback se aplica a erros de acordo com regras de combinação +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Referência completa da arquitetura: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Autenticação +## Authentication -- Rotas do painel (`/dashboard/*`) usam cookie `auth_token` -- O login utiliza hash de senha salva; substituto para `INITIAL_PASSWORD` -- `requireLogin` alternável via `/api/settings/require-login` -- As rotas `/v1/*` requerem opcionalmente a chave da API do portador quando `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/pt-BR/ARCHITECTURE.md b/docs/i18n/pt-BR/ARCHITECTURE.md index 1b7e0f1766..258d62df53 100644 --- a/docs/i18n/pt-BR/ARCHITECTURE.md +++ b/docs/i18n/pt-BR/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Arquitetura OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Última atualização: 18/02/2026_ +_Last updated: 2026-03-04_ -## Resumo Executivo +## Executive Summary -OmniRoute é um gateway de roteamento de IA local e painel construído em Next.js. -Ele fornece um único endpoint compatível com OpenAI (`/v1/*`) e roteia o tráfego entre vários provedores upstream com tradução, fallback, atualização de token e rastreamento de uso. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Capacidades principais: +Core capabilities: -- Superfície API compatível com OpenAI para CLI/ferramentas (28 provedores) -- Tradução de solicitação/resposta em formatos de provedores -- Fallback de combinação de modelos (sequência de vários modelos) -- Fallback em nível de conta (várias contas por provedor) -- Gerenciamento de conexão de provedor de chave OAuth + API -- Geração de incorporação via `/v1/embeddings` (6 provedores, 9 modelos) -- Geração de imagens via `/v1/images/generations` (4 provedores, 9 modelos) -- Pense na análise de tags (`...`) para modelos de raciocínio -- Sanitização de resposta para compatibilidade estrita com OpenAI SDK -- Normalização de funções (desenvolvedor→sistema, sistema→usuário) para compatibilidade entre provedores -- Conversão de saída estruturada (json_schema → Gemini responseSchema) -- Persistência local para provedores, chaves, aliases, combos, configurações, preços -- Acompanhamento de uso/custo e registro de solicitações -- Sincronização em nuvem opcional para sincronização de vários dispositivos/estado -- Lista de permissões/lista de bloqueio de IP para controle de acesso à API -- Pensando na gestão orçamentária (passthrough/auto/custom/adaptive) -- Injeção imediata do sistema global -- Rastreamento de sessão e impressão digital -- Limitação de taxa aprimorada por conta com perfis específicos do provedor -- Padrão de disjuntor para resiliência do provedor -- Proteção de rebanho anti-trovão com bloqueio mutex -- Cache de desduplicação de solicitação baseada em assinatura -- Camada de domínio: disponibilidade do modelo, regras de custo, política de fallback, política de bloqueio -- Persistência de estado de domínio (cache write-through SQLite para fallbacks, orçamentos, bloqueios, disjuntores) -- Mecanismo de política para avaliação centralizada de solicitações (bloqueio → orçamento → fallback) -- Solicitar telemetria com agregação de latência p50/p95/p99 -- ID de correlação (X-Request-Id) para rastreamento ponta a ponta -- Registro de auditoria de conformidade com cancelamento por chave de API -- Estrutura de avaliação para garantia de qualidade LLM -- Painel de UI de resiliência com status do disjuntor em tempo real -- Provedores OAuth modulares (12 módulos individuais em `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Modelo de tempo de execução primário: +Primary runtime model: -- As rotas do aplicativo Next.js em `src/app/api/*` implementam APIs de painel e APIs de compatibilidade -- Um núcleo SSE/roteamento compartilhado em `src/sse/*` + `open-sse/*` lida com execução, tradução, streaming, fallback e uso do provedor +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Escopo e limites +## Scope and Boundaries -### No escopo +### In Scope -- Tempo de execução do gateway local -- APIs de gerenciamento de painel -- Autenticação do provedor e atualização de token -- Solicitar tradução e streaming SSE -- Estado local + persistência de uso -- Orquestração opcional de sincronização em nuvem +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Fora do escopo +### Out of Scope -- Implementação de serviço em nuvem por trás de `NEXT_PUBLIC_CLOUD_URL` -- Plano de controle/SLA do provedor fora do processo local -- Os próprios binários CLI externos (Claude CLI, Codex CLI, etc.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Contexto do sistema de alto nível +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Componentes principais de tempo de execução +## Core Runtime Components -## 1) API e camada de roteamento (rotas de aplicativos Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Diretórios principais: +Main directories: -- `src/app/api/v1/*` e `src/app/api/v1beta/*` para APIs de compatibilidade -- `src/app/api/*` para APIs de gerenciamento/configuração -- Próximas reescritas em `next.config.mjs` mapeiam `/v1/*` para `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Rotas de compatibilidade importantes: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — inclui modelos personalizados com `custom: true` -- `src/app/api/v1/embeddings/route.ts` — geração de incorporação (6 provedores) -- `src/app/api/v1/images/generations/route.ts` — geração de imagens (4+ provedores incluindo Antigravidade/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — bate-papo dedicado por provedor -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — embeddings dedicados por provedor -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — imagens dedicadas por provedor +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Domínios de gerenciamento: +Management domains: -- Autenticação/configurações: `src/app/api/auth/*`, `src/app/api/settings/*` -- Provedores/conexões: `src/app/api/providers*` -- Nós do provedor: `src/app/api/provider-nodes*` -- Modelos personalizados: `src/app/api/provider-models` (GET/POST/DELETE) -- Catálogo de modelos: `src/app/api/models/catalog` (GET) -- Configuração de proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Chaves/aliases/combos/preços: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Uso: `src/app/api/usage/*` -- Sincronização/nuvem: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Ajudantes de ferramentas CLI: `src/app/api/cli-tools/*` -- Filtro IP: `src/app/api/settings/ip-filter` (GET/PUT) -- Orçamento pensado: `src/app/api/settings/thinking-budget` (GET/PUT) -- Prompt do sistema: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessões: `src/app/api/sessions` (GET) -- Limites de taxa: `src/app/api/rate-limits` (GET) -- Resiliência: `src/app/api/resilience` (GET/PATCH) — perfis de provedor, disjuntor, estado limite de taxa -- Redefinição de resiliência: `src/app/api/resilience/reset` (POST) — redefinir disjuntores + resfriamento -- Estatísticas de cache: `src/app/api/cache/stats` (GET/DELETE) -- Disponibilidade do modelo: `src/app/api/models/availability` (GET/POST) -- Telemetria: `src/app/api/telemetry/summary` (GET) -- Orçamento: `src/app/api/usage/budget` (GET/POST) -- Cadeias de fallback: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Auditoria de conformidade: `src/app/api/compliance/audit-log` (GET) -- Avaliações: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Políticas: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Núcleo de Tradução +## 2) SSE + Translation Core -Principais módulos de fluxo: +Main flow modules: -- Entrada: `src/sse/handlers/chat.ts` -- Orquestração principal: `open-sse/handlers/chatCore.ts` -- Adaptadores de execução do provedor: `open-sse/executors/*` -- Detecção de formato/configuração do provedor: `open-sse/services/provider.ts` -- Análise/resolução de modelo: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Lógica de substituição da conta: `open-sse/services/accountFallback.ts` -- Registro de tradução: `open-sse/translator/index.ts` -- Transformações de fluxo: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Extração/normalização de uso: `open-sse/utils/usageTracking.ts` -- Pense no analisador de tags: `open-sse/utils/thinkTagParser.ts` -- Manipulador de incorporação: `open-sse/handlers/embeddings.ts` -- Incorporação de registro de provedor: `open-sse/config/embeddingRegistry.ts` -- Manipulador de geração de imagem: `open-sse/handlers/imageGeneration.ts` -- Registro do provedor de imagens: `open-sse/config/imageRegistry.ts` -- Sanitização de resposta: `open-sse/handlers/responseSanitizer.ts` -- Normalização de função: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Serviços (lógica de negócios): +Services (business logic): -- Seleção/pontuação de conta: `open-sse/services/accountSelector.ts` -- Gerenciamento do ciclo de vida do contexto: `open-sse/services/contextManager.ts` -- Aplicação do filtro IP: `open-sse/services/ipFilter.ts` -- Acompanhamento de sessão: `open-sse/services/sessionManager.ts` -- Solicitar desduplicação: `open-sse/services/signatureCache.ts` -- Injeção de prompt do sistema: `open-sse/services/systemPrompt.ts` -- Pensando na gestão orçamentária: `open-sse/services/thinkingBudget.ts` -- Roteamento de modelo curinga: `open-sse/services/wildcardRouter.ts` -- Gerenciamento de limite de taxa: `open-sse/services/rateLimitManager.ts` -- Disjuntor: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Módulos da camada de domínio: +Domain layer modules: -- Disponibilidade do modelo: `src/lib/domain/modelAvailability.ts` -- Regras/orçamentos de custos: `src/lib/domain/costRules.ts` -- Política de substituto: `src/lib/domain/fallbackPolicy.ts` -- Resolvedor combinado: `src/lib/domain/comboResolver.ts` -- Política de bloqueio: `src/lib/domain/lockoutPolicy.ts` -- Mecanismo de política: `src/domain/policyEngine.ts` — bloqueio centralizado → orçamento → avaliação alternativa -- Catálogo de códigos de erro: `src/lib/domain/errorCodes.ts` -- ID da solicitação: `src/lib/domain/requestId.ts` -- Tempo limite de busca: `src/lib/domain/fetchTimeout.ts` -- Solicitar telemetria: `src/lib/domain/requestTelemetry.ts` -- Conformidade/auditoria: `src/lib/domain/compliance/index.ts` -- Corredor de avaliação: `src/lib/domain/evalRunner.ts` -- Persistência de estado de domínio: `src/lib/db/domainState.ts` — SQLite CRUD para cadeias de fallback, orçamentos, histórico de custos, estado de bloqueio, disjuntores +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Módulos do provedor OAuth (12 arquivos individuais em `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Índice de registro: `src/lib/oauth/providers/index.ts` -- Provedores individuais: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Thin wrapper: `src/lib/oauth/providers.ts` — reexportações de módulos individuais +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Camada de Persistência +## 3) Persistence Layer -Banco de dados de estado primário: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- arquivo: `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` quando definido, caso contrário, `~/.omniroute/db.json`) -- entidades: ProviderConnections, ProviderNodes, modelAliases, combos, apiKeys, configurações, preços, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Banco de dados de uso: +Usage persistence: -- `src/lib/usageDb.ts` -- arquivos: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- segue a mesma política de diretório base de `localDb` (`DATA_DIR`, então `XDG_CONFIG_HOME/omniroute` quando definido) -- decomposto em submódulos focados: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -Banco de dados de estado de domínio (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — Operações CRUD para estado de domínio -- Tabelas (criadas em `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Padrão de cache write-through: os mapas na memória são autoritativos em tempo de execução; as mutações são escritas de forma síncrona no SQLite; o estado é restaurado do banco de dados na inicialização a frio +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Superfícies de autenticação + segurança +## 4) Auth + Security Surfaces -- Autenticação de cookie do painel: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Geração/verificação de chave de API: `src/shared/utils/apiKey.ts` -- Os segredos do provedor persistiram nas entradas `providerConnections` -- Suporte a proxy de saída via `open-sse/utils/proxyFetch.ts` (env vars) e `open-sse/utils/networkProxy.ts` (configurável por provedor ou global) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Sincronização na nuvem +## 5) Cloud Sync -- Inicialização do agendador: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Tarefa periódica: `src/shared/services/cloudSyncScheduler.ts` -- Rota de controle: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Ciclo de vida da solicitação (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Fluxo substituto da conta +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -As decisões de fallback são orientadas por `open-sse/services/accountFallback.ts` usando códigos de status e heurísticas de mensagens de erro. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Integração do OAuth e ciclo de vida de atualização de token +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -A atualização durante o tráfego ativo é executada dentro de `open-sse/handlers/chatCore.ts` por meio do executor `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Ciclo de vida da sincronização na nuvem (ativar/sincronizar/desativar) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -A sincronização periódica é acionada por `CloudSyncScheduler` quando a nuvem está habilitada. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Modelo de dados e mapa de armazenamento +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Arquivos de armazenamento físico: +Physical storage files: -- estado principal: `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` quando definido, caso contrário, `~/.omniroute/db.json`) -- estatísticas de uso: `${DATA_DIR}/usage.json` -- solicitar linhas de registro: `${DATA_DIR}/log.txt` -- sessões opcionais de depuração de tradução/solicitação: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topologia de implantação +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Mapeamento de módulos (crítico para decisões) +## Module Mapping (Decision-Critical) -### Módulos de rota e API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: APIs de compatibilidade -- `src/app/api/v1/providers/[provider]/*`: rotas dedicadas por provedor (chat, embeddings, imagens) -- `src/app/api/providers*`: provedor CRUD, validação, teste -- `src/app/api/provider-nodes*`: gerenciamento de nó compatível personalizado -- `src/app/api/provider-models`: gerenciamento de modelo personalizado (CRUD) -- `src/app/api/models/catalog`: API de catálogo de modelos completo (todos os tipos agrupados por provedor) -- `src/app/api/oauth/*`: fluxos OAuth/código do dispositivo -- `src/app/api/keys*`: ciclo de vida da chave de API local -- `src/app/api/models/alias`: gerenciamento de alias -- `src/app/api/combos*`: gerenciamento de combinação alternativa -- `src/app/api/pricing`: substituições de preços para cálculo de custos -- `src/app/api/settings/proxy`: configuração de proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: teste de conectividade de proxy de saída (POST) -- `src/app/api/usage/*`: APIs de uso e registros -- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronização na nuvem e ajudantes voltados para a nuvem -- `src/app/api/cli-tools/*`: gravadores/verificadores de configuração CLI locais -- `src/app/api/settings/ip-filter`: lista de permissões/lista de bloqueios de IP (GET/PUT) -- `src/app/api/settings/thinking-budget`: configuração do orçamento do token de pensamento (GET/PUT) -- `src/app/api/settings/system-prompt`: prompt global do sistema (GET/PUT) -- `src/app/api/sessions`: listagem de sessões ativas (GET) -- `src/app/api/rate-limits`: status de limite de taxa por conta (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Núcleo de Roteamento e Execução +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: análise de solicitação, tratamento de combinação, loop de seleção de conta -- `open-sse/handlers/chatCore.ts`: tradução, envio do executor, manipulação de novas tentativas/atualizações, configuração de stream -- `open-sse/executors/*`: rede específica do provedor e comportamento do formato +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Registro de tradução e conversores de formato +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: registro e orquestração do tradutor -- Solicitar tradutores: `open-sse/translator/request/*` -- Tradutores de resposta: `open-sse/translator/response/*` -- Constantes de formato: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Persistência +### Persistence -- `src/lib/localDb.ts`: configuração/estado persistente -- `src/lib/usageDb.ts`: histórico de uso e registros de solicitação contínua +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Cobertura do Executor do Provedor (Padrão de Estratégia) +## Provider Executor Coverage (Strategy Pattern) -Cada provedor tem um executor especializado que estende `BaseExecutor` (em `open-sse/executors/base.ts`), que fornece construção de URL, construção de cabeçalho, nova tentativa com espera exponencial, ganchos de atualização de credenciais e o método de orquestração `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Executor | Fornecedor(es) | Tratamento Especial | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Juntos, Fireworks, Cerebras, Cohere, NVIDIA | Configuração dinâmica de URL/cabeçalho por provedor | -| `AntigravityExecutor` | Antigravidade do Google | IDs de projeto/sessão personalizados, análise repetida após | -| `CodexExecutor` | Códice OpenAI | Injeta instruções do sistema, força esforço de raciocínio | -| `CursorExecutor` | Cursor IDE | Protocolo ConnectRPC, codificação Protobuf, assinatura de solicitação via checksum | -| `GithubExecutor` | Copiloto GitHub | Atualização de token do copiloto, cabeçalhos que imitam VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binário AWS EventStream → conversão SSE | -| `GeminiCLIExecutor` | Gêmeos CLI | Ciclo de atualização do token OAuth do Google | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Todos os outros provedores (incluindo nós compatíveis personalizados) usam `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matriz de compatibilidade do provedor +## Provider Compatibility Matrix -| Provedor | Formato | Autenticação | Transmitir | Não-transmissão | Atualização de token | API de uso | -| ------------------------ | ---------------- | --------------------------------- | ---------------- | --------------- | -------------------- | ------------------------ | -| Cláudio | Cláudio | Chave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Somente administrador | -| Gêmeos | gêmeos | Chave API/OAuth | ✅ | ✅ | ✅ | ⚠️Console em nuvem | -| Gêmeos CLI | gêmeo-cli | OAuth | ✅ | ✅ | ✅ | ⚠️Console em nuvem | -| Antigravidade | antigravidade | OAuth | ✅ | ✅ | ✅ | ✅ API de cota completa | -| OpenAI | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Códice | respostas openai | OAuth | ✅ forçado | ❌ | ✅ | ✅ Limites de taxas | -| Copiloto GitHub | abrirai | OAuth + token de copiloto | ✅ | ✅ | ✅ | ✅ Instantâneos de cota | -| Cursor | cursor | Soma de verificação personalizada | ✅ | ✅ | ❌ | ❌ | -| Kiro | Kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limites de uso | -| Qwen | abrirai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação | -| iFlow | abrirai | OAuth (Básico) | ✅ | ✅ | ✅ | ⚠️ Por solicitação | -| OpenRouter | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | Cláudio | Chave API | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Groq | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| xAI (Groque) | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Mistral | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Perplexidade | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Juntos IA | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| IA de fogos de artifício | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Cérebros | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Coerente | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Cobertura de tradução de formato +## Format Translation Coverage -Os formatos de origem detectados incluem: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Os formatos de destino incluem: +Target formats include: -- Bate-papo/respostas OpenAI - -Cláudio -- Envelope Gemini/Gemini-CLI/Antigravidade - -Kiro +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro - Cursor -As traduções usam **OpenAI como formato de hub** — todas as conversões passam pelo OpenAI como intermediário: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -As traduções são selecionadas dinamicamente com base no formato da carga útil de origem e no formato de destino do provedor. +Translations are selected dynamically based on source payload shape and provider target format. -Camadas de processamento adicionais no pipeline de tradução: +Additional processing layers in the translation pipeline: -- **Sanitização de respostas** — Remove campos não padrão de respostas no formato OpenAI (streaming e não streaming) para garantir conformidade estrita com o SDK -- **Normalização de funções** — Converte `developer` → `system` para alvos não-OpenAI; mescla `system` → `user` para modelos que rejeitam a função do sistema (GLM, ERNIE) -- **Extração de tag Think** — Analisa blocos `...` do conteúdo no campo `reasoning_content` -- **Saída estruturada** — Converte OpenAI `response_format.json_schema` em `responseMimeType` + `responseSchema` do Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Terminais de API suportados +## Supported API Endpoints -| Ponto final | Formato | Manipulador | -| -------------------------------------------------- | ---------------------------- | -------------------------------------------------------------- | -| `POST /v1/chat/completions` | Bate-papo OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Mensagens de Cláudio | Mesmo manipulador (detectado automaticamente) | -| `POST /v1/responses` | Respostas OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Incorporações OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Listagem de modelos | Rota API | -| `POST /v1/images/generations` | Imagens OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Listagem de modelos | Rota API | -| `POST /v1/providers/{provider}/chat/completions` | Bate-papo OpenAI | Dedicado por provedor com validação de modelo | -| `POST /v1/providers/{provider}/embeddings` | Incorporações OpenAI | Dedicado por provedor com validação de modelo | -| `POST /v1/providers/{provider}/images/generations` | Imagens OpenAI | Dedicado por provedor com validação de modelo | -| `POST /v1/messages/count_tokens` | Contagem de tokens de Claude | Rota API | -| `GET /v1/models` | Lista de modelos OpenAI | Rota API (chat + incorporação + imagem + modelos customizados) | -| `GET /api/models/catalog` | Catálogo | Todos os modelos agrupados por fornecedor + tipo | -| `POST /v1beta/models/*:streamGenerateContent` | Nativo de Gêmeos | Rota API | -| `GET/PUT/DELETE /api/settings/proxy` | Configuração de proxy | Configuração de proxy de rede | -| `POST /api/settings/proxy/test` | Conectividade proxy | Endpoint de teste de integridade/conectividade do proxy | -| `GET/POST/DELETE /api/provider-models` | Modelos personalizados | Gestão de modelos customizados por provedor | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Ignorar manipulador +## Bypass Handler -O manipulador de bypass (`open-sse/utils/bypassHandler.ts`) intercepta solicitações "descartáveis" conhecidas da CLI de Claude — pings de aquecimento, extrações de títulos e contagens de tokens — e retorna uma **resposta falsa** sem consumir tokens do provedor upstream. Isso é acionado somente quando `User-Agent` contém `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Solicitar pipeline do registrador +## Request Logger Pipeline -O registrador de solicitações (`open-sse/utils/requestLogger.ts`) fornece um pipeline de registro de depuração de 7 estágios, desabilitado por padrão, habilitado por meio de `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Os arquivos são gravados em `/logs//` para cada sessão de solicitação. +Files are written to `/logs//` for each request session. -## Modos de falha e resiliência +## Failure Modes and Resilience -## 1) Disponibilidade da conta/provedor +## 1) Account/Provider Availability -- resfriamento da conta do provedor em erros transitórios/taxa/autenticação -- fallback da conta antes da falha na solicitação -- modelo combinado substituto quando o caminho do modelo/provedor atual se esgota +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Expiração do token +## 2) Token Expiry -- pré-verificação e atualização com nova tentativa para provedores atualizáveis -- Nova tentativa 401/403 após tentativa de atualização no caminho principal +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Segurança de transmissão +## 3) Stream Safety -- controlador de fluxo com reconhecimento de desconexão -- fluxo de tradução com liberação de fim de fluxo e manipulação de `[DONE]` -- fallback de estimativa de uso quando faltam metadados de uso do provedor +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Degradação da sincronização na nuvem +## 4) Cloud Sync Degradation -- erros de sincronização aparecem, mas o tempo de execução local continua -- o agendador tem lógica com capacidade de repetição, mas a execução periódica atualmente chama a sincronização de tentativa única por padrão +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integridade de dados +## 5) Data Integrity -- Migração/reparo de formato de banco de dados para chaves ausentes -- proteções de redefinição JSON corrompidas para localDb e usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Observabilidade e Sinais Operacionais +## Observability and Operational Signals -Fontes de visibilidade em tempo de execução: +Runtime visibility sources: -- registros do console de `src/sse/utils/logger.ts` -- agregados de uso por solicitação em `usage.json` -- registro de status da solicitação textual em `log.txt` -- registros opcionais de solicitação/tradução profunda em `logs/` quando `ENABLE_REQUEST_LOGS=true` -- endpoints de uso do painel (`/api/usage/*`) para consumo de UI +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Limites sensíveis à segurança +## Security-Sensitive Boundaries -- Segredo JWT (`JWT_SECRET`) protege a verificação/assinatura de cookies da sessão do painel -- O substituto de senha inicial (`INITIAL_PASSWORD`, padrão `123456`) deve ser substituído em implantações reais -- O segredo HMAC da chave de API (`API_KEY_SECRET`) protege o formato de chave de API local gerado -- Os segredos do provedor (chaves/tokens de API) persistem no banco de dados local e devem ser protegidos no nível do sistema de arquivos -- Os endpoints de sincronização em nuvem dependem da semântica de autenticação de chave de API + ID de máquina +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Matriz de Ambiente e Tempo de Execução +## Environment and Runtime Matrix -Variáveis de ambiente usadas ativamente pelo código: +Environment variables actively used by code: -- Aplicativo/autenticação: `JWT_SECRET`, `INITIAL_PASSWORD` -- Armazenamento: `DATA_DIR` -- Comportamento do nó compatível: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Substituição opcional da base de armazenamento (Linux/macOS quando `DATA_DIR` não definido): `XDG_CONFIG_HOME` -- Hash de segurança: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Registro: `ENABLE_REQUEST_LOGS` -- URL de sincronização/nuvem: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Proxy de saída: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` e variantes minúsculas -- Sinalizadores de recurso SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Auxiliares de plataforma/tempo de execução (não configuração específica do aplicativo): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Notas arquitetônicas conhecidas +## Known Architectural Notes -1. `usageDb` e `localDb` agora compartilham a mesma política de diretório base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) com migração de arquivo legado. -2. `/api/v1/route.ts` retorna uma lista de modelos estáticos e não é a principal fonte de modelos usada por `/v1/models`. -3. O registrador de solicitações grava cabeçalhos/corpo completos quando habilitado; trate o diretório de log como confidencial. -4. O comportamento da nuvem depende do `NEXT_PUBLIC_BASE_URL` correto e da acessibilidade do endpoint na nuvem. -5. O diretório `open-sse/` é publicado como o `@omniroute/open-sse` **pacote de espaço de trabalho npm**. O código-fonte o importa via `@omniroute/open-sse/...` (resolvido por Next.js `transpilePackages`). Os caminhos de arquivo neste documento ainda usam o nome de diretório `open-sse/` para consistência. -6. Os gráficos no painel usam **Recharts** (baseados em SVG) para visualizações analíticas interativas e acessíveis (gráficos de barras de uso de modelo, tabelas de detalhamento de fornecedores com taxas de sucesso). -7. Os testes E2E usam **Playwright** (`tests/e2e/`), executados via `npm run test:e2e`. Os testes de unidade usam o **executor de testes Node.js** (`tests/unit/`), executado por meio de `npm run test:plan3`. O código-fonte em `src/` é **TypeScript** (`.ts`/`.tsx`); o espaço de trabalho `open-sse/` permanece JavaScript (`.js`). -8. A página de configurações é organizada em 5 guias: Segurança, Roteamento (6 estratégias globais: preenchimento primeiro, round-robin, p2c, aleatório, menos usado, com custo otimizado), Resiliência (limites de taxa editáveis, disjuntor, políticas), IA (pensando no orçamento, prompt do sistema, cache de prompt), Avançado (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Lista de verificação de verificação operacional +## Operational Verification Checklist -- Construir a partir da fonte: `npm run build` -- Construir imagem Docker: `docker build -t omniroute .` -- Inicie o serviço e verifique: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- O URL base de destino da CLI deve ser `http://:20128/v1` quando `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md index 16693c3fb1..303880c198 100644 --- a/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Documentação da base de código +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Um guia abrangente e para iniciantes sobre o roteador proxy AI multiprovedor **omniroute**. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. O que é OmniRoute? +## 1. What Is omniroute? -omniroute é um **roteador proxy** que fica entre clientes de IA (Claude CLI, Codex, Cursor IDE, etc.) e provedores de IA (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Isso resolve um grande problema: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Diferentes clientes de IA falam "idiomas" diferentes (formatos de API), e diferentes provedores de IA também esperam "idiomas" diferentes.** omniroute traduz entre eles automaticamente. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Pense nisso como um tradutor universal nas Nações Unidas – qualquer delegado pode falar qualquer idioma, e o tradutor converte para qualquer outro delegado. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Visão geral da arquitetura +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Princípio Básico: Tradução Hub-and-Spoke +### Core Principle: Hub-and-Spoke Translation -Toda a tradução de formato passa pelo **formato OpenAI como hub**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Isso significa que você só precisa de **N tradutores** (um por formato) em vez de **N²** (cada par). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Estrutura do Projeto +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Divisão módulo por módulo +## 4. Module-by-Module Breakdown -### 4.1 Configuração (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -A **única fonte de verdade** para todas as configurações do provedor. +The **single source of truth** for all provider configuration. -| Arquivo | Finalidade | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `constants.ts` | Objeto `PROVIDERS` com URLs base, credenciais OAuth (padrões), cabeçalhos e prompts de sistema padrão para cada provedor. Também define `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` e `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Carrega credenciais externas de `data/provider-credentials.json` e as mescla nos padrões codificados em `PROVIDERS`. Mantém os segredos fora do controle de origem, mantendo a compatibilidade com versões anteriores. | -| `providerModels.ts` | Registro central de modelos: aliases de provedores de mapas → IDs de modelos. Funções como `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Instruções do sistema injetadas em solicitações do Codex (restrições de edição, regras de sandbox, políticas de aprovação). | -| `defaultThinkingSignature.ts` | Assinaturas de "pensamento" padrão para os modelos Claude e Gemini. | -| `ollamaModels.ts` | Definição de esquema para modelos locais de Ollama (nome, tamanho, família, quantização). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Fluxo de carregamento de credenciais +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Executores (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Os executores encapsulam **lógica específica do provedor** usando o **Padrão de estratégia**. Cada executor substitui os métodos básicos conforme necessário. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Executor | Provedor | Principais Especializações | -| ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Base abstrata: construção de URL, cabeçalhos, lógica de repetição, atualização de credenciais | -| `default.ts` | Claude, Gêmeos, OpenAI, GLM, Kimi, MiniMax | Atualização genérica de token OAuth para provedores padrão | -| `antigravity.ts` | Código do Google Cloud | Geração de ID de projeto/sessão, fallback de vários URLs, análise de repetição personalizada de mensagens de erro ("redefinir após 2h7m23s") | -| `cursor.ts` | Cursor IDE | **Mais complexo**: autenticação de soma de verificação SHA-256, codificação de solicitação Protobuf, EventStream binário → análise de resposta SSE | -| `codex.ts` | Códice OpenAI | Injeta instruções do sistema, gerencia níveis de pensamento, remove parâmetros não suportados | -| `gemini-cli.ts` | CLI do Google Gemini | Criação de URL personalizado (`streamGenerateContent`), atualização de token Google OAuth | -| `github.ts` | Copiloto GitHub | Sistema de token duplo (token GitHub OAuth + Copilot), imitação de cabeçalho VSCode | -| `kiro.ts` | AWS CodeWhisperer | Análise binária AWS EventStream, event frames AMZN, estimativa de token | -| `index.ts` | — | Fábrica: nome do provedor de mapas → classe do executor, com fallback padrão | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Manipuladores (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -A **camada de orquestração** — coordena tradução, execução, streaming e tratamento de erros. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Arquivo | Finalidade | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Orquestrador central** (~600 linhas). Lida com o ciclo de vida completo da solicitação: detecção de formato → tradução → envio do executor → resposta de streaming/não streaming → atualização de token → tratamento de erros → registro de uso. | -| `responsesHandler.ts` | Adaptador para API de respostas da OpenAI: converte o formato de respostas → conclusões de bate-papo → envia para `chatCore` → converte SSE de volta para o formato de respostas. | -| `embeddings.ts` | Manipulador de geração de incorporação: resolve o modelo de incorporação → provedor, despacha para a API do provedor, retorna uma resposta de incorporação compatível com OpenAI. Suporta mais de 6 provedores. | -| `imageGeneration.ts` | Manipulador de geração de imagem: resolve modelo de imagem → provedor, suporta modos compatíveis com OpenAI, imagem Gemini (Antigravidade) e fallback (Nebius). Retorna imagens base64 ou URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Ciclo de vida da solicitação (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Serviços (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Lógica de negócios que dá suporte aos manipuladores e executores. +Business logic that supports the handlers and executors. -| Arquivo | Finalidade | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Detecção de formato** (`detectFormat`): analisa a estrutura do corpo da solicitação para identificar formatos Claude/OpenAI/Gemini/Antigravity/Responses (inclui heurística `max_tokens` para Claude). Além disso: construção de URL, construção de cabeçalho, normalização de configuração de pensamento. Suporta provedores dinâmicos `openai-compatible-*` e `anthropic-compatible-*`. | -| `model.ts` | Análise de string de modelo (`claude/model-name` → `{provider: "claude", model: "model-name"}`), resolução de alias com detecção de colisão, limpeza de entrada (rejeita caracteres de passagem/controle de caminho) e resolução de informações de modelo com suporte a getter de alias assíncrono. | -| `accountFallback.ts` | Tratamento de limite de taxa: espera exponencial (1s → 2s → 4s → máx. 2min), gerenciamento de resfriamento da conta, classificação de erros (quais erros acionam fallback versus não). | -| `tokenRefresh.ts` | Atualização de token OAuth para **todos os provedores**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Inclui cache de desduplicação de promessa em andamento e nova tentativa com espera exponencial. | -| `combo.ts` | **Modelos combinados**: cadeias de modelos alternativos. Se o modelo A falhar com um erro elegível para fallback, tente o modelo B, depois o C, etc. Retorna os códigos de status upstream reais. | -| `usage.ts` | Busca dados de cota/uso de APIs do provedor (cotas do GitHub Copilot, cotas do modelo antigravidade, limites de taxa do Codex, detalhamentos de uso do Kiro, configurações do Claude). | -| `accountSelector.ts` | Seleção inteligente de conta com algoritmo de pontuação: considera prioridade, status de integridade, posição round-robin e estado de espera para escolher a conta ideal para cada solicitação. | -| `contextManager.ts` | Gerenciamento do ciclo de vida do contexto de solicitação: cria e rastreia objetos de contexto por solicitação com metadados (ID da solicitação, carimbos de data/hora, informações do provedor) para depuração e registro em log. | -| `ipFilter.ts` | Controle de acesso baseado em IP: suporta modos de lista de permissões e lista de bloqueios. Valida o IP do cliente em relação às regras configuradas antes de processar solicitações de API. | -| `sessionManager.ts` | Rastreamento de sessão com impressão digital do cliente: rastreia sessões ativas usando identificadores de cliente com hash, monitora contagens de solicitações e fornece métricas de sessão. | -| `signatureCache.ts` | Solicitar cache de desduplicação baseado em assinatura: evita solicitações duplicadas armazenando em cache assinaturas de solicitações recentes e retornando respostas armazenadas em cache para solicitações idênticas dentro de um intervalo de tempo. | -| `systemPrompt.ts` | Injeção global de prompt do sistema: acrescenta ou acrescenta um prompt do sistema configurável a todas as solicitações, com tratamento de compatibilidade por provedor. | -| `thinkingBudget.ts` | Gerenciamento de orçamento de token de raciocínio: oferece suporte aos modos passthrough, automático (configuração de pensamento), personalizado (orçamento fixo) e adaptativo (escala de complexidade) para controlar tokens de pensamento/raciocínio. | -| `wildcardRouter.ts` | Roteamento de padrão de modelo curinga: resolve padrões curinga (por exemplo, `*/claude-*`) para pares concretos de provedor/modelo com base na disponibilidade e prioridade. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Desduplicação de atualização de token +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Máquina de estado substituto da conta +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Cadeia de modelos combinados +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Tradutor (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -O **mecanismo de tradução de formatos** usando um sistema de plugins com autorregistro. +The **format translation engine** using a self-registering plugin system. -#### Arquitetura +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Diretório | Arquivos | Descrição | -| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `request/` | 8 tradutores | Converta corpos de solicitação entre formatos. Cada arquivo é registrado automaticamente via `register(from, to, fn)` na importação. | -| `response/` | 7 tradutores | Converta pedaços de resposta de streaming entre formatos. Lida com tipos de eventos SSE, blocos de pensamento e chamadas de ferramentas. | -| `helpers/` | 6 ajudantes | Utilitários compartilhados: `claudeHelper` (extração de prompt do sistema, configuração de pensamento), `geminiHelper` (mapeamento de partes/conteúdo), `openaiHelper` (filtragem de formato), `toolCallHelper` (geração de ID, injeção de resposta ausente), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Mecanismo de tradução: `translateRequest()`, `translateResponse()`, gerenciamento de estado, registro. | -| `formats.ts` | — | Constantes de formato: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Design principal: plug-ins de autorregistro +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Utilitários (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Arquivo | Finalidade | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Criação de resposta a erros (formato compatível com OpenAI), análise de erros upstream, extração de tempo de repetição antigravidade de mensagens de erro, streaming de erros SSE. | -| `stream.ts` | **SSE Transform Stream** — o principal pipeline de streaming. Dois modos: `TRANSLATE` (tradução de formato completo) e `PASSTHROUGH` (normalizar + extrair uso). Lida com buffer de blocos, estimativa de uso e rastreamento de comprimento de conteúdo. As instâncias do codificador/decodificador por fluxo evitam o estado compartilhado. | -| `streamHelpers.ts` | Utilitários SSE de baixo nível: `parseSSELine` (tolerante a espaços em branco), `hasValuableContent` (filtra pedaços vazios para OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialização SSE com reconhecimento de formato com limpeza `perf_metrics`). | -| `usageTracking.ts` | Extração de uso de token de qualquer formato (Claude/OpenAI/Gemini/Responses), estimativa com proporções separadas de caracteres por ferramenta/mensagem por token, adição de buffer (margem de segurança de 2.000 tokens), filtragem de campo específica de formato, registro de console com cores ANSI. | -| `requestLogger.ts` | Registro de solicitação baseado em arquivo (aceitação via `ENABLE_REQUEST_LOGS=true`). Cria pastas de sessão com arquivos numerados: `1_req_client.json` → `7_res_client.txt`. Toda E/S é assíncrona (dispare e esqueça). Mascara cabeçalhos sensíveis. | -| `bypassHandler.ts` | Intercepta padrões específicos do Claude CLI (extração de título, aquecimento, contagem) e retorna respostas falsas sem ligar para nenhum provedor. Suporta streaming e não streaming. Intencionalmente limitado ao escopo Claude CLI. | -| `networkProxy.ts` | Resolve URL de proxy de saída para um determinado provedor com precedência: configuração específica do provedor → configuração global → variáveis ​​de ambiente (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Suporta exclusões `NO_PROXY`. Configuração de caches por 30s. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Pipeline de streaming SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Estrutura da sessão do registrador de solicitações +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Camada de Aplicação (`src/`) +### 4.7 Application Layer (`src/`) -| Diretório | Finalidade | -| ------------- | -------------------------------------------------------------------------------------- | -| `src/app/` | UI da Web, rotas de API, middleware Express, manipuladores de retorno de chamada OAuth | -| `src/lib/` | Acesso à base de dados (`localDb.ts`, `usageDb.ts`), autenticação, partilhada | -| `src/mitm/` | Utilitários proxy man-in-the-middle para interceptar o tráfego do provedor | -| `src/models/` | Definições de modelo de banco de dados | -| `src/shared/` | Wrappers em torno de funções open-sse (provedor, fluxo, erro, etc.) | -| `src/sse/` | Manipuladores de endpoint SSE que conectam a biblioteca open-sse às rotas Express | -| `src/store/` | Gerenciamento de estado de aplicação | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Rotas de API notáveis +#### Notable API Routes -| Rota | Métodos | Finalidade | -| --------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | -| `/api/provider-models` | OBTER/POSTAR/EXCLUIR | CRUD para modelos customizados por provedor | -| `/api/models/catalog` | OBTER | Catálogo agregado de todos os modelos (chat, incorporação, imagem, customizado) agrupados por provedor | -| `/api/settings/proxy` | OBTER/COLOCAR/EXCLUIR | Configuração hierárquica de proxy de saída (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POSTAR | Valida a conectividade do proxy e retorna IP público/latência | -| `/v1/providers/[provider]/chat/completions` | POSTAR | Conclusões de chat dedicadas por provedor com validação de modelo | -| `/v1/providers/[provider]/embeddings` | POSTAR | Incorporações dedicadas por provedor com validação de modelo | -| `/v1/providers/[provider]/images/generations` | POSTAR | Geração de imagens dedicadas por provedor com validação de modelo | -| `/api/settings/ip-filter` | OBTER/COLOCAR | Gerenciamento de lista de permissão/lista de bloqueio de IP | -| `/api/settings/thinking-budget` | OBTER/COLOCAR | Configuração do orçamento do token de raciocínio (passagem/automática/personalizada/adaptável) | -| `/api/settings/system-prompt` | OBTER/COLOCAR | Injeção imediata do sistema global para todas as solicitações | -| `/api/sessions` | OBTER | Acompanhamento e métricas de sessões ativas | -| `/api/rate-limits` | OBTER | Status do limite de taxa por conta | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Principais padrões de design +## 5. Key Design Patterns -### 5.1 Tradução Hub-and-Spoke +### 5.1 Hub-and-Spoke Translation -Todos os formatos são traduzidos através do **formato OpenAI como hub**. Adicionar um novo provedor requer apenas escrever **um par** de tradutores (de/para OpenAI), não N pares. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Padrão de Estratégia do Executor +### 5.2 Executor Strategy Pattern -Cada provedor possui uma classe de executor dedicada herdada de `BaseExecutor`. A fábrica em `executors/index.ts` seleciona o correto em tempo de execução. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Sistema de plug-ins de autorregistro +### 5.3 Self-Registering Plugin System -Os módulos tradutores se registram na importação via `register()`. Adicionar um novo tradutor é apenas criar um arquivo e importá-lo. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Fallback de conta com backoff exponencial +### 5.4 Account Fallback with Exponential Backoff -Quando um provedor retorna 429/401/500, o sistema pode mudar para a próxima conta, aplicando cooldowns exponenciais (1s → 2s → 4s → máx. 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Cadeias de modelos combinados +### 5.5 Combo Model Chains -Um "combo" agrupa várias strings `provider/model`. Se o primeiro falhar, volte para o próximo automaticamente. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Tradução de streaming com estado +### 5.6 Stateful Streaming Translation -A tradução de resposta mantém o estado em blocos SSE (rastreamento de blocos de pensamento, acúmulo de chamadas de ferramentas, indexação de blocos de conteúdo) por meio do mecanismo `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Buffer de segurança de uso +### 5.7 Usage Safety Buffer -Um buffer de 2.000 tokens é adicionado ao uso relatado para evitar que os clientes atinjam os limites da janela de contexto devido à sobrecarga dos prompts do sistema e da tradução de formato. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Formatos Suportados +## 6. Supported Formats -| Formato | Direção | Identificador | -| ------------------------------ | ---------------- | ------------------ | -| Conclusões do bate-papo OpenAI | origem + destino | `openai` | -| API de respostas OpenAI | origem + destino | `openai-responses` | -| Claude Antrópico | origem + destino | `claude` | -| Google Gêmeos | origem + destino | `gemini` | -| CLI do Google Gemini | apenas alvo | `gemini-cli` | -| Antigravidade | origem + destino | `antigravity` | -| AWSKiro | apenas alvo | `kiro` | -| Cursor | apenas alvo | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Provedores Suportados +## 7. Supported Providers -| Provedor | Método de autenticação | Executor | Notas principais | -| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------- | -| Claude Antrópico | Chave API ou OAuth | Padrão | Usa cabeçalho `x-api-key` | -| Google Gêmeos | Chave API ou OAuth | Padrão | Usa cabeçalho `x-goog-api-key` | -| CLI do Google Gemini | OAuth | GêmeosCLI | Usa ponto de extremidade `streamGenerateContent` | -| Antigravidade | OAuth | Antigravidade | Fallback de vários URLs, análise de repetição personalizada | -| OpenAI | Chave de API | Padrão | Autenticação do portador padrão | -| Códice | OAuth | Códice | Injeta instruções do sistema, gerencia o pensamento | -| Copiloto GitHub | Token OAuth + Copiloto | GitHub | Token duplo, imitação de cabeçalho VSCode | -| Kiro (AWS) | AWS SSO OIDC ou social | Kiro | Análise binária de EventStream | -| Cursor IDE | Autenticação de soma de verificação | Cursor | Codificação protobuf, somas de verificação SHA-256 | -| Qwen | OAuth | Padrão | Autenticação padrão | -| iFlow | OAuth (Básico + Portador) | Padrão | Cabeçalho de autenticação dupla | -| OpenRouter | Chave de API | Padrão | Autenticação do portador padrão | -| GLM, Kimi, MiniMax | Chave de API | Padrão | Compatível com Claude, use `x-api-key` | -| `openai-compatible-*` | Chave de API | Padrão | Dinâmico: qualquer endpoint compatível com OpenAI | -| `anthropic-compatible-*` | Chave de API | Padrão | Dinâmico: qualquer endpoint compatível com Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Resumo do fluxo de dados +## 8. Data Flow Summary -### Solicitação de streaming +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Solicitação de não streaming +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Desviar fluxo (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/pt-BR/FEATURES.md b/docs/i18n/pt-BR/FEATURES.md index 599e62469b..82cc73b67b 100644 --- a/docs/i18n/pt-BR/FEATURES.md +++ b/docs/i18n/pt-BR/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Galeria de recursos do painel +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Guia visual para cada seção do painel do OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Provedores +## 🔌 Providers -Gerencie conexões de provedores de IA: provedores OAuth (Claude Code, Codex, Gemini CLI), provedores de chaves de API (Groq, DeepSeek, OpenRouter) e provedores gratuitos (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨Combos +## 🎨 Combos -Crie combos de roteamento de modelos com 6 estratégias: preenchimento primeiro, round-robin, potência de duas opções, aleatório, menos usado e com custo otimizado. Cada combinação encadeia vários modelos com fallback automático. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Análise +## 📊 Analytics -Análise de uso abrangente com consumo de tokens, estimativas de custos, mapas de calor de atividades, gráficos de distribuição semanais e detalhamentos por provedor. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Saúde do Sistema +## 🏥 System Health -Monitoramento em tempo real: tempo de atividade, memória, versão, percentis de latência (p50/p95/p99), estatísticas de cache e estados de disjuntores do provedor. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Parque do Tradutor +## 🔧 Translator Playground -Quatro modos para depurar traduções de API: **Playground** (conversor de formato), **Chat Tester** (solicitações ao vivo), **Test Bench** (testes em lote) e **Live Monitor** (transmissão em tempo real). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Configurações +## 🎮 Model Playground _(v2.0.9+)_ -Configurações gerais, armazenamento do sistema, gerenciamento de backup (banco de dados de exportação/importação), aparência (modo escuro/claro), segurança (inclui proteção de endpoint de API e bloqueio de provedor personalizado), roteamento, resiliência e configuração avançada. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Ferramentas CLI +## 🔧 CLI Tools -Configuração com um clique para ferramentas de codificação de IA: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code e Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Solicitar registros +## 🤖 CLI Agents _(v2.0.11+)_ -Registro de solicitações em tempo real com filtragem por provedor, modelo, conta e chave de API. Mostra códigos de status, uso de token, latência e detalhes de resposta. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Ponto final da API +## 🌐 API Endpoint -Seu endpoint de API unificado com detalhamento de recursos: conclusões de bate-papo, incorporações, geração de imagens, reclassificação, transcrição de áudio e chaves de API registradas. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/pt-BR/TROUBLESHOOTING.md b/docs/i18n/pt-BR/TROUBLESHOOTING.md index 5066922892..120092d63c 100644 --- a/docs/i18n/pt-BR/TROUBLESHOOTING.md +++ b/docs/i18n/pt-BR/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Solução de problemas +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Problemas e soluções comuns para OmniRoute. +Common problems and solutions for OmniRoute. --- -## Correções rápidas +## Quick Fixes -| Problema | Solução | -| ----------------------------------------- | -------------------------------------------------------------------------------------- | -| O primeiro login não funciona | Verifique `INITIAL_PASSWORD` em `.env` (padrão: `123456`) | -| Painel abre na porta errada | Definir `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Nenhum registro de solicitação em `logs/` | Definir `ENABLE_REQUEST_LOGS=true` | -| EACCES: permissão negada | Defina `DATA_DIR=/path/to/writable/dir` para substituir `~/.omniroute` | -| Estratégia de roteamento não salva | Atualização para v1.4.11+ (correção do esquema Zod para persistência de configurações) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Problemas do provedor +## Provider Issues -### "O modelo de linguagem não forneceu mensagens" +### "Language model did not provide messages" -**Causa:** Cota do provedor esgotada. +**Cause:** Provider quota exhausted. -**Correção:** +**Fix:** -1. Verifique o rastreador de cota do painel -2. Use um combo com níveis alternativos -3. Mude para um nível mais barato/gratuito +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Limitação de taxa +### Rate Limiting -**Causa:** Cota de assinatura esgotada. +**Cause:** Subscription quota exhausted. -**Correção:** +**Fix:** -- Adicionar substituto: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Use GLM/MiniMax como backup barato +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Token OAuth expirado +### OAuth Token Expired -OmniRoute atualiza automaticamente os tokens. Se os problemas persistirem: +OmniRoute auto-refreshes tokens. If issues persist: -1. Painel → Provedor → Reconectar -2. Exclua e adicione novamente a conexão do provedor +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Problemas de nuvem +## Cloud Issues -### Erros de sincronização na nuvem +### Cloud Sync Errors -1. Verifique `BASE_URL` aponta para sua instância em execução (por exemplo, `http://localhost:20128`) -2. Verifique os pontos `CLOUD_URL` para seu endpoint de nuvem (por exemplo, `https://omniroute.dev`) -3. Mantenha os valores `NEXT_PUBLIC_*` alinhados com os valores do lado do servidor +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Nuvem `stream=false` Retorna 500 +### Cloud `stream=false` Returns 500 -**Sintoma:** `Unexpected token 'd'...` no endpoint da nuvem para chamadas sem streaming. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Causa:** O upstream retorna a carga SSE enquanto o cliente espera JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Solução alternativa:** use `stream=true` para chamadas diretas na nuvem. O tempo de execução local inclui substituto SSE→JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud diz conectado, mas "chave de API inválida" +### Cloud Says Connected but "Invalid API key" -1. Crie uma nova chave no painel local (`/api/keys`) -2. Execute a sincronização na nuvem: Habilite Nuvem → Sincronizar agora -3. Chaves antigas/não sincronizadas ainda podem retornar `401` na nuvem +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Problemas do Docker +## Docker Issues -### A ferramenta CLI mostra não instalada +### CLI Tool Shows Not Installed -1. Verifique os campos de tempo de execução: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Para modo portátil: use o destino de imagem `runner-cli` (CLIs agrupados) -3. Para o modo de montagem do host: defina `CLI_EXTRA_PATHS` e monte o diretório bin do host como somente leitura -4. Se `installed=true` e `runnable=false`: o binário foi encontrado, mas falhou na verificação de integridade +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Validação Rápida de Tempo de Execução +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Problemas de custo +## Cost Issues -### Custos elevados +### High Costs -1. Verifique as estatísticas de uso em Painel → Uso -2. Mude o modelo primário para GLM/MiniMax -3. Use o nível gratuito (Gemini CLI, iFlow) para tarefas não críticas -4. Defina orçamentos de custos por chave de API: Painel → Chaves de API → Orçamento +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Depuração +## Debugging -### Habilitar registros de solicitação +### Enable Request Logs -Defina `ENABLE_REQUEST_LOGS=true` em seu arquivo `.env`. Os logs aparecem no diretório `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Verifique a integridade do provedor +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Armazenamento em tempo de execução +### Runtime Storage -- Estado principal: `${DATA_DIR}/db.json` (provedores, combos, aliases, chaves, configurações) -- Uso: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Registros de solicitação: `/logs/...` (quando `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Problemas com disjuntores +## Circuit Breaker Issues -### Provedor preso no estado OPEN +### Provider stuck in OPEN state -Quando o disjuntor de um provedor está ABERTO, as solicitações são bloqueadas até que o tempo de espera expire. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Correção:** +**Fix:** -1. Vá para **Painel → Configurações → Resiliência** -2. Verifique a placa do disjuntor do provedor afetado -3. Clique em **Redefinir tudo** para limpar todos os disjuntores ou aguarde o tempo de espera expirar -4. Verifique se o provedor está realmente disponível antes de redefinir +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### O provedor continua desarmando o disjuntor +### Provider keeps tripping the circuit breaker -Se um provedor entrar repetidamente no estado OPEN: +If a provider repeatedly enters OPEN state: -1. Verifique **Dashboard → Health → Provider Health** para ver o padrão de falha -2. Vá para **Configurações → Resiliência → Perfis do Provedor** e aumente o limite de falha -3. Verifique se o provedor alterou os limites da API ou requer nova autenticação -4. Revise a telemetria de latência – alta latência pode causar falhas baseadas em tempo limite +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problemas de transcrição de áudio +## Audio Transcription Issues -### Erro "Modelo não suportado" +### "Unsupported model" error -- Certifique-se de usar o prefixo correto: `deepgram/nova-3` ou `assemblyai/best` -- Verifique se o provedor está conectado em **Painel → Provedores** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### A transcrição retorna vazia ou falha +### Transcription returns empty or fails -- Verifique os formatos de áudio suportados: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Verifique se o tamanho do arquivo está dentro dos limites do provedor (normalmente <25 MB) -- Verifique a validade da chave API do provedor no cartão do provedor +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Depuração do tradutor +## Translator Debugging -Use **Dashboard → Tradutor** para depurar problemas de tradução de formato: +Use **Dashboard → Translator** to debug format translation issues: -| Modo | Quando usar | -| ------------------------- | --------------------------------------------------------------------------------------------------------------- | -| **Parque Infantil** | Compare os formatos de entrada/saída lado a lado — cole uma solicitação com falha para ver como ela é traduzida | -| **Testador de bate-papo** | Envie mensagens ao vivo e inspecione a carga completa de solicitação/resposta, incluindo cabeçalhos | -| **Banco de testes** | Execute testes em lote em combinações de formatos para descobrir quais traduções estão quebradas | -| **Monitoramento ao vivo** | Observe o fluxo de solicitações em tempo real para detectar problemas intermitentes de tradução | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Problemas comuns de formato +### Common format issues -- **Tags de pensamento não aparecem** — Verifique se o provedor alvo apoia o pensamento e a configuração do orçamento de pensamento -- **Queda de chamadas de ferramentas** — Algumas traduções de formato podem remover campos não suportados; verificar no modo Playground -- **Prompt do sistema ausente** — Claude e Gemini lidam com os prompts do sistema de maneira diferente; verifique o resultado da tradução -- **SDK retorna string bruta em vez de objeto** — Corrigido na v1.1.0: o sanitizador de resposta agora remove campos não padrão (`x_groq`, `usage_breakdown`, etc.) que causam falhas de validação do OpenAI SDK Pydantic -- **GLM/ERNIE rejeita função `system`** — Corrigido na v1.1.0: o normalizador de função mescla automaticamente mensagens do sistema em mensagens do usuário para modelos incompatíveis -- Função **`developer` não reconhecida** — Corrigido na v1.1.0: convertido automaticamente para `system` para provedores não-OpenAI -- **`json_schema` não funciona com Gemini** — Corrigido na v1.1.0: `response_format` agora é convertido para `responseMimeType` + `responseSchema` do Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Configurações de resiliência +## Resilience Settings -### Limite de taxa automático não acionado +### Auto rate-limit not triggering -- O limite automático de taxa se aplica apenas a provedores de chaves de API (não a OAuth/assinatura) -- Verifique se **Configurações → Resiliência → Perfis do Provedor** tem limite de taxa automática ativado -- Verifique se o provedor retorna códigos de status `429` ou cabeçalhos `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Ajustando a espera exponencial +### Tuning exponential backoff -Os perfis do provedor oferecem suporte a estas configurações: +Provider profiles support these settings: -- **Atraso base** — Tempo de espera inicial após a primeira falha (padrão: 1s) -- **Atraso máximo** — Limite máximo de tempo de espera (padrão: 30s) -- **Multiplicador** — Quanto aumentar o atraso por falha consecutiva (padrão: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Rebanho anti-trovão +### Anti-thundering herd -Quando muitas solicitações simultâneas atingem um provedor com taxa limitada, o OmniRoute usa mutex + limitação automática de taxa para serializar solicitações e evitar falhas em cascata. Isso é automático para provedores de chaves de API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Ainda preso? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Problemas do GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arquitetura**: Consulte [link](ARCHITECTURE.md) para detalhes internos -- **Referência da API**: Consulte [link](API_REFERENCE.md) para todos os endpoints -- **Painel de saúde**: verifique **Painel → Saúde** para ver o status do sistema em tempo real -- **Tradutor**: Use **Dashboard → Tradutor** para depurar problemas de formato +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/pt-BR/USER_GUIDE.md b/docs/i18n/pt-BR/USER_GUIDE.md index d1a6876022..5a043224df 100644 --- a/docs/i18n/pt-BR/USER_GUIDE.md +++ b/docs/i18n/pt-BR/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Guia do usuário +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Guia completo para configurar provedores, criar combos, integrar ferramentas CLI e implantar OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Índice +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Guia completo para configurar provedores, criar combos, integrar ferramentas CLI --- -## 💰 Visão geral dos preços +## 💰 Pricing at a Glance -| Nível | Provedor | Custo | Redefinição de cota | Melhor para | -| ------------------- | ------------------------ | ---------------- | ------------------------ | ----------------------------- | -| **💳 ASSINATURA** | Código Claude (Pro) | $ 20/mês | 5h + semanalmente | Já inscrito | -| | Códice (Plus/Pro) | US$ 20-200/mês | 5h + semanalmente | Usuários OpenAI | -| | Gêmeos CLI | **GRÁTIS** | 180 mil/mês + 1 mil/dia | Todos! | -| | Copiloto GitHub | US$ 10-19/mês | Mensalmente | Usuários do GitHub | -| **🔑 CHAVE DE API** | DeepSeek | Pague por uso | Nenhum | Raciocínio barato | -| | Groq | Pague por uso | Nenhum | Inferência ultrarrápida | -| | xAI (Groque) | Pague por uso | Nenhum | Raciocínio Grok 4 | -| | Mistral | Pague por uso | Nenhum | Modelos hospedados na UE | -| | Perplexidade | Pague por uso | Nenhum | Pesquisa aumentada | -| | Juntos IA | Pague por uso | Nenhum | Modelos de código aberto | -| | IA de fogos de artifício | Pague por uso | Nenhum | Imagens FLUX rápidas | -| | Cérebros | Pague por uso | Nenhum | Velocidade em escala de wafer | -| | Coerente | Pague por uso | Nenhum | Comando R+ RAG | -| | NVIDIA NIM | Pague por uso | Nenhum | Modelos empresariais | -| **💰 BARATO** | GLM-4.7 | US$ 0,6/1 milhão | Diariamente 10h | Backup de orçamento | -| | MiniMax M2.1 | US$ 0,2/1 milhão | Rolamento de 5 horas | Opção mais barata | -| | Kimi K2 | $ 9 / mês fixo | 10 milhões de tokens/mês | Custo previsível | -| **🆓 GRÁTIS** | iFlow | $0 | Ilimitado | 8 modelos grátis | -| | Qwen | $0 | Ilimitado | 3 modelos grátis | -| | Kiro | $0 | Ilimitado | Cláudio grátis | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Dica profissional:** Comece com Gemini CLI (180 mil grátis/mês) + combo iFlow (gratuito ilimitado) = custo de $ 0! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Casos de uso +## 🎯 Use Cases -### Caso 1: "Tenho assinatura do Claude Pro" +### Case 1: "I have Claude Pro subscription" -**Problema:** A cota expira sem ser utilizada, limites de taxa durante codificação pesada +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Caso 2: "Quero custo zero" +### Case 2: "I want zero cost" -**Problema:** Não posso pagar assinaturas, preciso de codificação de IA confiável +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Caso 3: "Preciso de codificação 24 horas por dia, 7 dias por semana, sem interrupções" +### Case 3: "I need 24/7 coding, no interruptions" -**Problema:** Prazos, não podemos arcar com o tempo de inatividade +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Caso 4: "Quero IA GRATUITA no OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Problema:** Precisa de assistente de IA em aplicativos de mensagens, totalmente gratuito +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Configuração do provedor +## 📖 Provider Setup -### 🔐 Provedores de assinatura +### 🔐 Subscription Providers -#### Código Claude (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Dica profissional:** Use o Opus para tarefas complexas e o Sonnet para velocidade. OmniRoute rastreia cota por modelo! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (GRÁTIS 180 mil/mês!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Melhor valor:** Grande nível gratuito! Use isso antes dos níveis pagos. +**Best Value:** Huge free tier! Use this before paid tiers. -#### GitHub Copiloto +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Fornecedores baratos +### 💰 Cheap Providers -#### GLM-4.7 (redefinição diária, US$ 0,6/1 milhão) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Inscreva-se: [Zhipu AI](https://open.bigmodel.cn/) -2. Obtenha a chave API do plano de codificação -3. Painel → Adicionar chave de API: Provedor: `glm`, chave de API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Usar:** `glm/glm-4.7` — **Dica profissional:** O plano de codificação oferece 3× cota a 1/7 de custo! Redefinir diariamente às 10h. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (redefinição de 5h, US$ 0,20/1 milhão) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Inscreva-se: [MiniMax](https://www.minimax.io/) -2. Obter chave de API → Painel → Adicionar chave de API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Use:** `minimax/MiniMax-M2.1` — **Dica profissional:** Opção mais barata para contexto longo (1 milhão de tokens)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (US$ 9/mês fixo) +#### Kimi K2 ($9/month flat) -1. Inscreva-se: [Moonshot AI](https://platform.moonshot.ai/) -2. Obter chave de API → Painel → Adicionar chave de API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Uso:** `kimi/kimi-latest` — **Dica profissional:** Fixo US$ 9/mês para 10 milhões de tokens = US$ 0,90/1 milhão de custo efetivo! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 Provedores GRATUITOS +### 🆓 FREE Providers -#### iFlow (8 modelos GRATUITOS) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 modelos GRATUITOS) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRÁTIS) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨Combos +## 🎨 Combos -### Exemplo 1: Maximize a assinatura → Backup barato +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Exemplo 2: somente gratuito (custo zero) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,7 +249,7 @@ Cost: $0 forever! --- -## 🔧 Integração CLI +## 🔧 CLI Integration ### Cursor IDE @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Código Cláudio +### Claude Code -Editar `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Editar `~/.claude/config.json`: } ``` -### CLI do Codex +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -279,9 +279,9 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -###OpenClaw +### OpenClaw -Editar `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Editar `~/.openclaw/openclaw.json`: } ``` -**Ou use o Dashboard:** Ferramentas CLI → OpenClaw → Configuração automática +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Continuar / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Implantação +## 🚀 Deployment -### Implantação VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Para o modo integrado ao host com binários CLI, consulte a seção Docker na documentação principal. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Variáveis de Ambiente +### Environment Variables -| Variável | Padrão | Descrição | -| --------------------- | ------------------------------------ | --------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Segredo de assinatura do JWT (**mudança na produção**) | -| `INITIAL_PASSWORD` | `123456` | Senha do primeiro login | -| `DATA_DIR` | `~/.omniroute` | Diretório de dados (banco de dados, uso, logs) | -| `PORT` | padrão da estrutura | Porta de serviço (`20128` em exemplos) | -| `HOSTNAME` | padrão da estrutura | Host de vinculação (o padrão do Docker é `0.0.0.0`) | -| `NODE_ENV` | padrão de tempo de execução | Definir `production` para implantação | -| `BASE_URL` | `http://localhost:20128` | URL base interna do lado do servidor | -| `CLOUD_URL` | `https://omniroute.dev` | URL base do endpoint de sincronização em nuvem | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Segredo HMAC para chaves de API geradas | -| `REQUIRE_API_KEY` | `false` | Aplicar chave de API do portador em `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Habilita registros de solicitação/resposta | -| `AUTH_COOKIE_SECURE` | `false` | Forçar cookie de autenticação `Secure` (atrás do proxy reverso HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Para obter a referência completa da variável de ambiente, consulte [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Modelos Disponíveis +## 📊 Available Models
-Ver todos os modelos disponíveis +View all available models -**Código Claude (`cc/`)** — Pro/Máx: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Códice (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATUITO: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Copiloto do GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — US$ 0,6/1 milhão: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — US$ 0,2/1 milhão: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATUITO: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATUITO: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATUITO: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,15 +460,15 @@ Para obter a referência completa da variável de ambiente, consulte [README](.. **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Perplexidade (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Juntos AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**IA do Fireworks (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Cérebros (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Coerente (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Para obter a referência completa da variável de ambiente, consulte [README](.. --- -## 🧩 Recursos avançados +## 🧩 Advanced Features -### Modelos personalizados +### Custom Models -Adicione qualquer ID de modelo a qualquer provedor sem esperar por uma atualização do aplicativo: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Ou use o Dashboard: **Provedores → [Provedor] → Modelos personalizados**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Rotas de provedores dedicados +### Dedicated Provider Routes -Encaminhe solicitações diretamente para um provedor específico com validação de modelo: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -O prefixo do provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Configuração de proxy de rede +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Precedência:** Específico da chave → Específico do combo → Específico do provedor → Global → Ambiente. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API de catálogo de modelos +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Retorna modelos agrupados por provedor com tipos (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Sincronização na nuvem +### Cloud Sync -- Sincronize provedores, combos e configurações entre dispositivos -- Sincronização automática em segundo plano com tempo limite + falha rápida -- Prefira `BASE_URL`/`CLOUD_URL` do lado do servidor na produção +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (Fase 9) +### LLM Gateway Intelligence (Phase 9) -- **Cache Semântico** — Armazena automaticamente em cache sem streaming, temperatura = 0 respostas (ignorar com `X-OmniRoute-No-Cache: true`) -- **Idempotência de solicitação** — Desduplica solicitações em 5s por meio do cabeçalho `Idempotency-Key` ou `X-Request-Id` -- **Acompanhamento de progresso** — Eventos SSE `event: progress` de aceitação por meio do cabeçalho `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Parque do Tradutor +### Translator Playground -Acesso via **Painel → Tradutor**. Depure e visualize como o OmniRoute traduz solicitações de API entre provedores. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Modo | Finalidade | -| ------------------------- | ----------------------------------------------------------------------------------------------------------- | -| **Parque Infantil** | Selecione os formatos de origem/destino, cole uma solicitação e veja o resultado traduzido instantaneamente | -| **Testador de bate-papo** | Envie mensagens de chat ao vivo através do proxy e inspecione todo o ciclo de solicitação/resposta | -| **Banco de testes** | Execute testes em lote em múltiplas combinações de formatos para verificar a exatidão da tradução | -| **Monitoramento ao vivo** | Assista às traduções em tempo real enquanto as solicitações fluem pelo proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Casos de uso:** +**Use cases:** -- Depure por que uma combinação específica de cliente/provedor falha -- Verifique se as tags de pensamento, as chamadas de ferramentas e os prompts do sistema são traduzidos corretamente -- Compare as diferenças de formato entre os formatos OpenAI, Claude, Gemini e Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Estratégias de roteamento +### Routing Strategies -Configure via **Painel → Configurações → Roteamento**. +Configure via **Dashboard → Settings → Routing**. -| Estratégia | Descrição | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| **Preencha primeiro** | Usa contas em ordem de prioridade – a conta principal lida com todas as solicitações até ficar indisponível | -| **Round Robin** | Percorre todas as contas com um limite fixo configurável (padrão: 3 chamadas por conta) | -| **P2C (Poder de Duas Escolhas)** | Escolhe 2 contas aleatórias e direciona para a mais saudável — equilibra a carga com a consciência da saúde | -| **Aleatório** | Seleciona aleatoriamente uma conta para cada solicitação usando o embaralhamento Fisher-Yates | -| **Menos usado** | Roteia para a conta com o carimbo de data/hora `lastUsedAt` mais antigo, distribuindo o tráfego uniformemente | -| **Custo Otimizado** | Rotas para a conta com menor valor de prioridade, otimizando para provedores de menor custo | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Aliases de modelo curinga +#### Wildcard Model Aliases -Crie padrões curinga para remapear nomes de modelos: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Os curingas suportam `*` (qualquer caractere) e `?` (caractere único). +Wildcards support `*` (any characters) and `?` (single character). -#### Cadeias substitutas +#### Fallback Chains -Defina cadeias de fallback globais que se aplicam a todas as solicitações: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Resiliência e Disjuntores +### Resilience & Circuit Breakers -Configure via **Painel → Configurações → Resiliência**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementa resiliência em nível de provedor com quatro componentes: +OmniRoute implements provider-level resilience with four components: -1. **Perfis de Provedores** — Configuração por provedor para: - - Limite de falha (quantas falhas antes da abertura) - - Duração do resfriamento - - Sensibilidade de detecção de limite de taxa - - Parâmetros de espera exponencial +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Limites de taxa editáveis** — Padrões de nível de sistema configuráveis no painel: - - **Solicitações por minuto (RPM)** — Máximo de solicitações por minuto por conta - - **Tempo mínimo entre solicitações** — Intervalo mínimo em milissegundos entre solicitações - - **Máximo de solicitações simultâneas** — Máximo de solicitações simultâneas por conta - - Clique em **Editar** para modificar e depois em **Salvar** ou **Cancelar**. Os valores persistem por meio da API de resiliência. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Disjuntor** — Rastreia falhas por provedor e abre automaticamente o circuito quando um limite é atingido: - - **FECHADO** (Saudável) — As solicitações fluem normalmente - - **OPEN** — O provedor é bloqueado temporariamente após falhas repetidas - - **HALF_OPEN** — Testando se o provedor se recuperou +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Políticas e identificadores bloqueados** — Mostra o status do disjuntor e identificadores bloqueados com capacidade de desbloqueio forçado. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Detecção automática de limite de taxa** — Monitora os cabeçalhos `429` e `Retry-After` para evitar proativamente atingir os limites de taxa do provedor. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Dica profissional:** Use o botão **Redefinir tudo** para limpar todos os disjuntores e resfriamentos quando um provedor se recupera de uma interrupção. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Exportação/Importação de banco de dados +### Database Export / Import -Gerencie backups de banco de dados em **Painel → Configurações → Sistema e armazenamento**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Ação | Descrição | -| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Exportar banco de dados** | Baixa o banco de dados SQLite atual como um arquivo `.sqlite` | -| **Exportar tudo (.tar.gz)** | Baixa um arquivo de backup completo, incluindo: banco de dados, configurações, combos, conexões de provedor (sem credenciais), metadados de chave API | -| **Importar banco de dados** | Faça upload de um arquivo `.sqlite` para substituir o banco de dados atual. Um backup de pré-importação é criado automaticamente | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Validação de importação:** O arquivo importado é validado quanto à integridade (verificação de pragma SQLite), tabelas necessárias (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) e tamanho (máximo de 100 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Casos de uso:** +**Use Cases:** -- Migrar OmniRoute entre máquinas -- Crie backups externos para recuperação de desastres -- Compartilhe configurações entre membros da equipe (exportar tudo → compartilhar arquivo) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Painel de configurações +### Settings Dashboard -A página de configurações está organizada em 5 guias para facilitar a navegação: +The settings page is organized into 5 tabs for easy navigation: -| Guia | Conteúdo | -| --------------- | ----------------------------------------------------------------------------------------------------------------- | -| **Segurança** | Configurações de login/senha, controle de acesso IP, autenticação de API para `/models` e bloqueio de provedor | -| **Roteamento** | Estratégia de roteamento global (6 opções), aliases de modelo curinga, cadeias de fallback, padrões de combinação | -| **Resiliência** | Perfis de provedores, limites de taxas editáveis, status de disjuntores, políticas e identificadores bloqueados | -| **IA** | Pensando na configuração do orçamento, injeção de prompt do sistema global, estatísticas de cache de prompt | -| **Avançado** | Configuração de proxy global (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Gestão de Custos e Orçamento +### Costs & Budget Management -Acesso via **Painel → Custos**. +Access via **Dashboard → Costs**. -| Guia | Finalidade | -| ------------- | -------------------------------------------------------------------------------------------------------------- | -| **Orçamento** | Defina limites de gastos por chave de API com orçamentos diários/semanais/mensais e rastreamento em tempo real | -| **Preços** | Visualize e edite entradas de preços de modelo — custo por 1 mil tokens de entrada/saída por provedor | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Acompanhamento de custos:** cada solicitação registra o uso do token e calcula o custo usando a tabela de preços. Veja detalhes em **Painel → Uso** por provedor, modelo e chave de API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Transcrição de áudio +### Audio Transcription -OmniRoute oferece suporte à transcrição de áudio por meio do endpoint compatível com OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Provedores disponíveis: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Formatos de áudio suportados: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Estratégias de balanceamento de combinação +### Combo Balancing Strategies -Configure o balanceamento por combo em **Painel → Combos → Criar/Editar → Estratégia**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Estratégia | Descrição | -| ------------------- | ----------------------------------------------------------------------------------------- | -| **Round-Robin** | Gira pelos modelos sequencialmente | -| **Prioridade** | Tenta sempre o primeiro modelo; recorre apenas ao erro | -| **Aleatório** | Escolhe um modelo aleatório do combo para cada solicitação | -| **Ponderada** | Rotas proporcionalmente com base nos pesos atribuídos por modelo | -| **Menos usado** | Rotas para o modelo com o menor número de solicitações recentes (usa métricas combinadas) | -| **Custo Otimizado** | Rotas para o modelo mais barato disponível (usa tabela de preços) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Os padrões de combinação global podem ser definidos em **Painel → Configurações → Roteamento → Padrões de combinação**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Painel de saúde +### Health Dashboard -Acesso via **Painel → Saúde**. Visão geral da integridade do sistema em tempo real com 6 cartões: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Cartão | O que mostra | -| -------------------------- | ----------------------------------------------------------------------- | -| **Status do sistema** | Tempo de atividade, versão, uso de memória, diretório de dados | -| **Provedor de Saúde** | Estado do disjuntor por fornecedor (Fechado/Aberto/Meio-aberto) | -| **Limites de Tarifas** | Cooldowns de limite de taxa ativa por conta com tempo restante | -| **Bloqueios ativos** | Prestadores bloqueados temporariamente pela política de lockout | -| **Cache de Assinaturas** | Estatísticas do cache de desduplicação (chaves ativas, taxa de acertos) | -| **Telemetria de latência** | Agregação de latência p50/p95/p99 por provedor | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Dica profissional:** a página Saúde é atualizada automaticamente a cada 10 segundos. Use a placa do disjuntor para identificar quais provedores estão enfrentando problemas. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/pt/API_REFERENCE.md b/docs/i18n/pt/API_REFERENCE.md index 2c0ae042a1..b795722c11 100644 --- a/docs/i18n/pt/API_REFERENCE.md +++ b/docs/i18n/pt/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Referência de API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Referência completa para todos os endpoints da API OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Índice +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Referência completa para todos os endpoints da API OmniRoute. --- -## Conclusões de bate-papo +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Cabeçalhos personalizados +### Custom Headers -| Cabeçalho | Direção | Descrição | -| ------------------------ | ----------- | ---------------------------------------------------------- | -| `X-OmniRoute-No-Cache` | Solicitação | Defina como `true` para ignorar o cache | -| `X-OmniRoute-Progress` | Solicitação | Defina como `true` para eventos de progresso | -| `Idempotency-Key` | Solicitação | Chave de desduplicação (janela 5s) | -| `X-Request-Id` | Solicitação | Chave de desduplicação alternativa | -| `X-OmniRoute-Cache` | Resposta | `HIT` ou `MISS` (sem streaming) | -| `X-OmniRoute-Idempotent` | Resposta | `true` se desduplicado | -| `X-OmniRoute-Progress` | Resposta | `enabled` se o acompanhamento do progresso estiver ativado | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Incorporações +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Provedores disponíveis: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Geração de imagem +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Provedores disponíveis: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Listar modelos +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Terminais de compatibilidade +## Compatibility Endpoints -| Método | Caminho | Formato | -| ------ | --------------------------- | -------------------- | -| POSTAR | `/v1/chat/completions` | OpenAI | -| POSTAR | `/v1/messages` | Antrópico | -| POSTAR | `/v1/responses` | Respostas OpenAI | -| POSTAR | `/v1/embeddings` | OpenAI | -| POSTAR | `/v1/images/generations` | OpenAI | -| OBTER | `/v1/models` | OpenAI | -| POSTAR | `/v1/messages/count_tokens` | Antrópico | -| OBTER | `/v1beta/models` | Gêmeos | -| POSTAR | `/v1beta/models/{...path}` | Gêmeos gera conteúdo | -| POSTAR | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Rotas de provedores dedicados +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -O prefixo do provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Cache Semântico +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Exemplo de resposta: +Response example: ```json { @@ -162,154 +162,164 @@ Exemplo de resposta: --- -## Painel e gerenciamento +## Dashboard & Management -### Autenticação +### Authentication -| Ponto final | Método | Descrição | -| ----------------------------- | ------------- | ------------------------- | -| `/api/auth/login` | POSTAR | Entrar | -| `/api/auth/logout` | POSTAR | Sair | -| `/api/settings/require-login` | OBTER/COLOCAR | Alternar login necessário | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Gerenciamento de Provedores +### Provider Management -| Ponto final | Método | Descrição | -| ---------------------------- | --------------------- | -------------------------------- | -| `/api/providers` | OBTER/POSTAR | Listar/criar provedores | -| `/api/providers/[id]` | OBTER/COLOCAR/EXCLUIR | Gerenciar um provedor | -| `/api/providers/[id]/test` | POSTAR | Testar conexão do provedor | -| `/api/providers/[id]/models` | OBTER | Listar modelos de provedores | -| `/api/providers/validate` | POSTAR | Validar configuração do provedor | -| `/api/provider-nodes*` | Vários | Gerenciamento de nós de provedor | -| `/api/provider-models` | OBTER/POSTAR/EXCLUIR | Modelos personalizados | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Fluxos OAuth +### OAuth Flows -| Ponto final | Método | Descrição | -| -------------------------------- | ------ | ---------------------------- | -| `/api/oauth/[provider]/[action]` | Vários | OAuth específico do provedor | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Roteamento e configuração +### Routing & Config -| Ponto final | Método | Descrição | -| --------------------- | ------------ | -------------------------------------- | -| `/api/models/alias` | OBTER/POSTAR | Aliases de modelo | -| `/api/models/catalog` | OBTER | Todos os modelos por fornecedor + tipo | -| `/api/combos*` | Vários | Gestão de combos | -| `/api/keys*` | Vários | Gerenciamento de chaves API | -| `/api/pricing` | OBTER | Preços do modelo | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Uso e análise +### Usage & Analytics -| Ponto final | Método | Descrição | -| --------------------------- | ------ | ---------------------------- | -| `/api/usage/history` | OBTER | Histórico de uso | -| `/api/usage/logs` | OBTER | Registros de uso | -| `/api/usage/request-logs` | OBTER | Logs em nível de solicitação | -| `/api/usage/[connectionId]` | OBTER | Uso por conexão | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Configurações +### Settings -| Ponto final | Método | Descrição | -| ------------------------------- | ------------- | -------------------------------------------- | -| `/api/settings` | OBTER/COLOCAR | Configurações gerais | -| `/api/settings/proxy` | OBTER/COLOCAR | Configuração de proxy de rede | -| `/api/settings/proxy/test` | POSTAR | Testar conexão proxy | -| `/api/settings/ip-filter` | OBTER/COLOCAR | Lista de permissões/lista de bloqueios de IP | -| `/api/settings/thinking-budget` | OBTER/COLOCAR | Orçamento de token de raciocínio | -| `/api/settings/system-prompt` | OBTER/COLOCAR | Alerta do sistema global | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Monitoramento +### Monitoring -| Ponto final | Método | Descrição | -| ------------------------ | ------------- | ------------------------------ | -| `/api/sessions` | OBTER | Acompanhamento de sessão ativa | -| `/api/rate-limits` | OBTER | Limites de taxas por conta | -| `/api/monitoring/health` | OBTER | Exame de saúde | -| `/api/cache` | OBTER/EXCLUIR | Estatísticas de cache/limpar | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Backup e exportação/importação +### Backup & Export/Import -| Ponto final | Método | Descrição | -| --------------------------- | ------- | ------------------------------------------------------- | -| `/api/db-backups` | OBTER | Listar backups disponíveis | -| `/api/db-backups` | COLOCAR | Crie um backup manual | -| `/api/db-backups` | POSTAR | Restaurar de um backup específico | -| `/api/db-backups/export` | OBTER | Baixe o banco de dados como arquivo .sqlite | -| `/api/db-backups/import` | POSTAR | Carregar arquivo .sqlite para substituir banco de dados | -| `/api/db-backups/exportAll` | OBTER | Baixe o backup completo como arquivo .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Sincronização na nuvem +### Cloud Sync -| Ponto final | Método | Descrição | -| ---------------------- | ------ | ----------------------------------- | -| `/api/sync/cloud` | Vários | Operações de sincronização em nuvem | -| `/api/sync/initialize` | POSTAR | Inicializar sincronização | -| `/api/cloud/*` | Vários | Gerenciamento de nuvem | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Ferramentas CLI +### CLI Tools -| Ponto final | Método | Descrição | -| ---------------------------------- | ------ | ------------------------------ | -| `/api/cli-tools/claude-settings` | OBTER | Status CLI de Claude | -| `/api/cli-tools/codex-settings` | OBTER | Status da CLI do Codex | -| `/api/cli-tools/droid-settings` | OBTER | Status da CLI do Droid | -| `/api/cli-tools/openclaw-settings` | OBTER | Status da CLI do OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | OBTER | Tempo de execução CLI genérico | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -As respostas CLI incluem: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Resiliência e limites de taxas +### ACP Agents -| Ponto final | Método | Descrição | -| ----------------------- | ------------- | ------------------------------------- | -| `/api/resilience` | OBTER/COLOCAR | Obter/atualizar perfis de resiliência | -| `/api/resilience/reset` | POSTAR | Reinicializar disjuntores | -| `/api/rate-limits` | OBTER | Status do limite de taxa por conta | -| `/api/rate-limit` | OBTER | Configuração de limite de taxa global | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Avaliações +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Ponto final | Método | Descrição | -| ------------ | ------------ | --------------------------------------------- | -| `/api/evals` | OBTER/POSTAR | Listar suítes de avaliação/executar avaliação | +### Resilience & Rate Limits -### Políticas +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Ponto final | Método | Descrição | -| --------------- | -------------------- | --------------------------------- | -| `/api/policies` | OBTER/POSTAR/EXCLUIR | Gerenciar políticas de roteamento | +### Evals -### Conformidade +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Ponto final | Método | Descrição | -| --------------------------- | ------ | ----------------------------------------------- | -| `/api/compliance/audit-log` | OBTER | Registo de auditoria de conformidade (último N) | +### Policies -### v1beta (compatível com Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Ponto final | Método | Descrição | -| -------------------------- | ------ | --------------------------------------------- | -| `/v1beta/models` | OBTER | Listar modelos no formato Gemini | -| `/v1beta/models/{...path}` | POSTAR | Ponto de extremidade Gêmeos `generateContent` | +### Compliance -Esses endpoints refletem o formato API do Gemini para clientes que esperam compatibilidade nativa do Gemini SDK. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### APIs internas/do sistema +### v1beta (Gemini-Compatible) -| Ponto final | Método | Descrição | -| --------------- | ------ | ----------------------------------------------------------------------- | -| `/api/init` | OBTER | Verificação de inicialização do aplicativo (usada na primeira execução) | -| `/api/tags` | OBTER | Tags de modelo compatíveis com Ollama (para clientes Ollama) | -| `/api/restart` | POSTAR | Acionar reinicialização normal do servidor | -| `/api/shutdown` | POSTAR | Acionar o desligamento normal do servidor | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Observação:** Esses endpoints são usados internamente pelo sistema ou para compatibilidade do cliente Ollama. Eles normalmente não são chamados pelos usuários finais. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Transcrição de áudio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transcreva arquivos de áudio usando Deepgram ou AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Solicitação:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Resposta:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Provedores suportados:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Formatos suportados:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Compatibilidade com Ollama +## Ollama Compatibility -Para clientes que usam o formato API do Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -As solicitações são traduzidas automaticamente entre o Ollama e os formatos internos. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetria +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Resposta:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Orçamento +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Disponibilidade do modelo +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Processamento de solicitação +## Request Processing -1. Cliente envia solicitação para `/v1/*` -2. O manipulador de rota chama `handleChat`, `handleEmbedding`, `handleAudioTranscription` ou `handleImageGeneration` -3. O modelo foi resolvido (provedor/modelo direto ou alias/combo) -4. Credenciais selecionadas do banco de dados local com filtragem de disponibilidade de conta -5. Para bate-papo: `handleChatCore` — detecção de formato, tradução, verificação de cache, verificação de idempotência -6. O executor do provedor envia uma solicitação upstream -7. Resposta traduzida de volta para o formato do cliente (chat) ou retornada como está (incorporações/imagens/áudio) -8. Uso/registro registrado -9. Fallback se aplica a erros de acordo com regras de combinação +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Referência completa da arquitetura: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Autenticação +## Authentication -- Rotas do painel (`/dashboard/*`) usam cookie `auth_token` -- O login utiliza hash de senha salva; substituto para `INITIAL_PASSWORD` -- `requireLogin` alternável via `/api/settings/require-login` -- As rotas `/v1/*` requerem opcionalmente a chave da API do portador quando `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/pt/ARCHITECTURE.md b/docs/i18n/pt/ARCHITECTURE.md index 1b7e0f1766..258d62df53 100644 --- a/docs/i18n/pt/ARCHITECTURE.md +++ b/docs/i18n/pt/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Arquitetura OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Última atualização: 18/02/2026_ +_Last updated: 2026-03-04_ -## Resumo Executivo +## Executive Summary -OmniRoute é um gateway de roteamento de IA local e painel construído em Next.js. -Ele fornece um único endpoint compatível com OpenAI (`/v1/*`) e roteia o tráfego entre vários provedores upstream com tradução, fallback, atualização de token e rastreamento de uso. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Capacidades principais: +Core capabilities: -- Superfície API compatível com OpenAI para CLI/ferramentas (28 provedores) -- Tradução de solicitação/resposta em formatos de provedores -- Fallback de combinação de modelos (sequência de vários modelos) -- Fallback em nível de conta (várias contas por provedor) -- Gerenciamento de conexão de provedor de chave OAuth + API -- Geração de incorporação via `/v1/embeddings` (6 provedores, 9 modelos) -- Geração de imagens via `/v1/images/generations` (4 provedores, 9 modelos) -- Pense na análise de tags (`...`) para modelos de raciocínio -- Sanitização de resposta para compatibilidade estrita com OpenAI SDK -- Normalização de funções (desenvolvedor→sistema, sistema→usuário) para compatibilidade entre provedores -- Conversão de saída estruturada (json_schema → Gemini responseSchema) -- Persistência local para provedores, chaves, aliases, combos, configurações, preços -- Acompanhamento de uso/custo e registro de solicitações -- Sincronização em nuvem opcional para sincronização de vários dispositivos/estado -- Lista de permissões/lista de bloqueio de IP para controle de acesso à API -- Pensando na gestão orçamentária (passthrough/auto/custom/adaptive) -- Injeção imediata do sistema global -- Rastreamento de sessão e impressão digital -- Limitação de taxa aprimorada por conta com perfis específicos do provedor -- Padrão de disjuntor para resiliência do provedor -- Proteção de rebanho anti-trovão com bloqueio mutex -- Cache de desduplicação de solicitação baseada em assinatura -- Camada de domínio: disponibilidade do modelo, regras de custo, política de fallback, política de bloqueio -- Persistência de estado de domínio (cache write-through SQLite para fallbacks, orçamentos, bloqueios, disjuntores) -- Mecanismo de política para avaliação centralizada de solicitações (bloqueio → orçamento → fallback) -- Solicitar telemetria com agregação de latência p50/p95/p99 -- ID de correlação (X-Request-Id) para rastreamento ponta a ponta -- Registro de auditoria de conformidade com cancelamento por chave de API -- Estrutura de avaliação para garantia de qualidade LLM -- Painel de UI de resiliência com status do disjuntor em tempo real -- Provedores OAuth modulares (12 módulos individuais em `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Modelo de tempo de execução primário: +Primary runtime model: -- As rotas do aplicativo Next.js em `src/app/api/*` implementam APIs de painel e APIs de compatibilidade -- Um núcleo SSE/roteamento compartilhado em `src/sse/*` + `open-sse/*` lida com execução, tradução, streaming, fallback e uso do provedor +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Escopo e limites +## Scope and Boundaries -### No escopo +### In Scope -- Tempo de execução do gateway local -- APIs de gerenciamento de painel -- Autenticação do provedor e atualização de token -- Solicitar tradução e streaming SSE -- Estado local + persistência de uso -- Orquestração opcional de sincronização em nuvem +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Fora do escopo +### Out of Scope -- Implementação de serviço em nuvem por trás de `NEXT_PUBLIC_CLOUD_URL` -- Plano de controle/SLA do provedor fora do processo local -- Os próprios binários CLI externos (Claude CLI, Codex CLI, etc.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Contexto do sistema de alto nível +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Componentes principais de tempo de execução +## Core Runtime Components -## 1) API e camada de roteamento (rotas de aplicativos Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Diretórios principais: +Main directories: -- `src/app/api/v1/*` e `src/app/api/v1beta/*` para APIs de compatibilidade -- `src/app/api/*` para APIs de gerenciamento/configuração -- Próximas reescritas em `next.config.mjs` mapeiam `/v1/*` para `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Rotas de compatibilidade importantes: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — inclui modelos personalizados com `custom: true` -- `src/app/api/v1/embeddings/route.ts` — geração de incorporação (6 provedores) -- `src/app/api/v1/images/generations/route.ts` — geração de imagens (4+ provedores incluindo Antigravidade/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — bate-papo dedicado por provedor -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — embeddings dedicados por provedor -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — imagens dedicadas por provedor +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Domínios de gerenciamento: +Management domains: -- Autenticação/configurações: `src/app/api/auth/*`, `src/app/api/settings/*` -- Provedores/conexões: `src/app/api/providers*` -- Nós do provedor: `src/app/api/provider-nodes*` -- Modelos personalizados: `src/app/api/provider-models` (GET/POST/DELETE) -- Catálogo de modelos: `src/app/api/models/catalog` (GET) -- Configuração de proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Chaves/aliases/combos/preços: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Uso: `src/app/api/usage/*` -- Sincronização/nuvem: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Ajudantes de ferramentas CLI: `src/app/api/cli-tools/*` -- Filtro IP: `src/app/api/settings/ip-filter` (GET/PUT) -- Orçamento pensado: `src/app/api/settings/thinking-budget` (GET/PUT) -- Prompt do sistema: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessões: `src/app/api/sessions` (GET) -- Limites de taxa: `src/app/api/rate-limits` (GET) -- Resiliência: `src/app/api/resilience` (GET/PATCH) — perfis de provedor, disjuntor, estado limite de taxa -- Redefinição de resiliência: `src/app/api/resilience/reset` (POST) — redefinir disjuntores + resfriamento -- Estatísticas de cache: `src/app/api/cache/stats` (GET/DELETE) -- Disponibilidade do modelo: `src/app/api/models/availability` (GET/POST) -- Telemetria: `src/app/api/telemetry/summary` (GET) -- Orçamento: `src/app/api/usage/budget` (GET/POST) -- Cadeias de fallback: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Auditoria de conformidade: `src/app/api/compliance/audit-log` (GET) -- Avaliações: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Políticas: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + Núcleo de Tradução +## 2) SSE + Translation Core -Principais módulos de fluxo: +Main flow modules: -- Entrada: `src/sse/handlers/chat.ts` -- Orquestração principal: `open-sse/handlers/chatCore.ts` -- Adaptadores de execução do provedor: `open-sse/executors/*` -- Detecção de formato/configuração do provedor: `open-sse/services/provider.ts` -- Análise/resolução de modelo: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Lógica de substituição da conta: `open-sse/services/accountFallback.ts` -- Registro de tradução: `open-sse/translator/index.ts` -- Transformações de fluxo: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Extração/normalização de uso: `open-sse/utils/usageTracking.ts` -- Pense no analisador de tags: `open-sse/utils/thinkTagParser.ts` -- Manipulador de incorporação: `open-sse/handlers/embeddings.ts` -- Incorporação de registro de provedor: `open-sse/config/embeddingRegistry.ts` -- Manipulador de geração de imagem: `open-sse/handlers/imageGeneration.ts` -- Registro do provedor de imagens: `open-sse/config/imageRegistry.ts` -- Sanitização de resposta: `open-sse/handlers/responseSanitizer.ts` -- Normalização de função: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Serviços (lógica de negócios): +Services (business logic): -- Seleção/pontuação de conta: `open-sse/services/accountSelector.ts` -- Gerenciamento do ciclo de vida do contexto: `open-sse/services/contextManager.ts` -- Aplicação do filtro IP: `open-sse/services/ipFilter.ts` -- Acompanhamento de sessão: `open-sse/services/sessionManager.ts` -- Solicitar desduplicação: `open-sse/services/signatureCache.ts` -- Injeção de prompt do sistema: `open-sse/services/systemPrompt.ts` -- Pensando na gestão orçamentária: `open-sse/services/thinkingBudget.ts` -- Roteamento de modelo curinga: `open-sse/services/wildcardRouter.ts` -- Gerenciamento de limite de taxa: `open-sse/services/rateLimitManager.ts` -- Disjuntor: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Módulos da camada de domínio: +Domain layer modules: -- Disponibilidade do modelo: `src/lib/domain/modelAvailability.ts` -- Regras/orçamentos de custos: `src/lib/domain/costRules.ts` -- Política de substituto: `src/lib/domain/fallbackPolicy.ts` -- Resolvedor combinado: `src/lib/domain/comboResolver.ts` -- Política de bloqueio: `src/lib/domain/lockoutPolicy.ts` -- Mecanismo de política: `src/domain/policyEngine.ts` — bloqueio centralizado → orçamento → avaliação alternativa -- Catálogo de códigos de erro: `src/lib/domain/errorCodes.ts` -- ID da solicitação: `src/lib/domain/requestId.ts` -- Tempo limite de busca: `src/lib/domain/fetchTimeout.ts` -- Solicitar telemetria: `src/lib/domain/requestTelemetry.ts` -- Conformidade/auditoria: `src/lib/domain/compliance/index.ts` -- Corredor de avaliação: `src/lib/domain/evalRunner.ts` -- Persistência de estado de domínio: `src/lib/db/domainState.ts` — SQLite CRUD para cadeias de fallback, orçamentos, histórico de custos, estado de bloqueio, disjuntores +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Módulos do provedor OAuth (12 arquivos individuais em `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Índice de registro: `src/lib/oauth/providers/index.ts` -- Provedores individuais: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Thin wrapper: `src/lib/oauth/providers.ts` — reexportações de módulos individuais +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Camada de Persistência +## 3) Persistence Layer -Banco de dados de estado primário: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- arquivo: `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` quando definido, caso contrário, `~/.omniroute/db.json`) -- entidades: ProviderConnections, ProviderNodes, modelAliases, combos, apiKeys, configurações, preços, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Banco de dados de uso: +Usage persistence: -- `src/lib/usageDb.ts` -- arquivos: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- segue a mesma política de diretório base de `localDb` (`DATA_DIR`, então `XDG_CONFIG_HOME/omniroute` quando definido) -- decomposto em submódulos focados: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -Banco de dados de estado de domínio (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — Operações CRUD para estado de domínio -- Tabelas (criadas em `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Padrão de cache write-through: os mapas na memória são autoritativos em tempo de execução; as mutações são escritas de forma síncrona no SQLite; o estado é restaurado do banco de dados na inicialização a frio +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Superfícies de autenticação + segurança +## 4) Auth + Security Surfaces -- Autenticação de cookie do painel: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Geração/verificação de chave de API: `src/shared/utils/apiKey.ts` -- Os segredos do provedor persistiram nas entradas `providerConnections` -- Suporte a proxy de saída via `open-sse/utils/proxyFetch.ts` (env vars) e `open-sse/utils/networkProxy.ts` (configurável por provedor ou global) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Sincronização na nuvem +## 5) Cloud Sync -- Inicialização do agendador: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Tarefa periódica: `src/shared/services/cloudSyncScheduler.ts` -- Rota de controle: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Ciclo de vida da solicitação (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Fluxo substituto da conta +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -As decisões de fallback são orientadas por `open-sse/services/accountFallback.ts` usando códigos de status e heurísticas de mensagens de erro. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Integração do OAuth e ciclo de vida de atualização de token +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -A atualização durante o tráfego ativo é executada dentro de `open-sse/handlers/chatCore.ts` por meio do executor `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Ciclo de vida da sincronização na nuvem (ativar/sincronizar/desativar) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -A sincronização periódica é acionada por `CloudSyncScheduler` quando a nuvem está habilitada. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Modelo de dados e mapa de armazenamento +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Arquivos de armazenamento físico: +Physical storage files: -- estado principal: `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` quando definido, caso contrário, `~/.omniroute/db.json`) -- estatísticas de uso: `${DATA_DIR}/usage.json` -- solicitar linhas de registro: `${DATA_DIR}/log.txt` -- sessões opcionais de depuração de tradução/solicitação: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topologia de implantação +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Mapeamento de módulos (crítico para decisões) +## Module Mapping (Decision-Critical) -### Módulos de rota e API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: APIs de compatibilidade -- `src/app/api/v1/providers/[provider]/*`: rotas dedicadas por provedor (chat, embeddings, imagens) -- `src/app/api/providers*`: provedor CRUD, validação, teste -- `src/app/api/provider-nodes*`: gerenciamento de nó compatível personalizado -- `src/app/api/provider-models`: gerenciamento de modelo personalizado (CRUD) -- `src/app/api/models/catalog`: API de catálogo de modelos completo (todos os tipos agrupados por provedor) -- `src/app/api/oauth/*`: fluxos OAuth/código do dispositivo -- `src/app/api/keys*`: ciclo de vida da chave de API local -- `src/app/api/models/alias`: gerenciamento de alias -- `src/app/api/combos*`: gerenciamento de combinação alternativa -- `src/app/api/pricing`: substituições de preços para cálculo de custos -- `src/app/api/settings/proxy`: configuração de proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: teste de conectividade de proxy de saída (POST) -- `src/app/api/usage/*`: APIs de uso e registros -- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronização na nuvem e ajudantes voltados para a nuvem -- `src/app/api/cli-tools/*`: gravadores/verificadores de configuração CLI locais -- `src/app/api/settings/ip-filter`: lista de permissões/lista de bloqueios de IP (GET/PUT) -- `src/app/api/settings/thinking-budget`: configuração do orçamento do token de pensamento (GET/PUT) -- `src/app/api/settings/system-prompt`: prompt global do sistema (GET/PUT) -- `src/app/api/sessions`: listagem de sessões ativas (GET) -- `src/app/api/rate-limits`: status de limite de taxa por conta (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Núcleo de Roteamento e Execução +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: análise de solicitação, tratamento de combinação, loop de seleção de conta -- `open-sse/handlers/chatCore.ts`: tradução, envio do executor, manipulação de novas tentativas/atualizações, configuração de stream -- `open-sse/executors/*`: rede específica do provedor e comportamento do formato +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Registro de tradução e conversores de formato +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: registro e orquestração do tradutor -- Solicitar tradutores: `open-sse/translator/request/*` -- Tradutores de resposta: `open-sse/translator/response/*` -- Constantes de formato: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Persistência +### Persistence -- `src/lib/localDb.ts`: configuração/estado persistente -- `src/lib/usageDb.ts`: histórico de uso e registros de solicitação contínua +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Cobertura do Executor do Provedor (Padrão de Estratégia) +## Provider Executor Coverage (Strategy Pattern) -Cada provedor tem um executor especializado que estende `BaseExecutor` (em `open-sse/executors/base.ts`), que fornece construção de URL, construção de cabeçalho, nova tentativa com espera exponencial, ganchos de atualização de credenciais e o método de orquestração `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Executor | Fornecedor(es) | Tratamento Especial | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Juntos, Fireworks, Cerebras, Cohere, NVIDIA | Configuração dinâmica de URL/cabeçalho por provedor | -| `AntigravityExecutor` | Antigravidade do Google | IDs de projeto/sessão personalizados, análise repetida após | -| `CodexExecutor` | Códice OpenAI | Injeta instruções do sistema, força esforço de raciocínio | -| `CursorExecutor` | Cursor IDE | Protocolo ConnectRPC, codificação Protobuf, assinatura de solicitação via checksum | -| `GithubExecutor` | Copiloto GitHub | Atualização de token do copiloto, cabeçalhos que imitam VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binário AWS EventStream → conversão SSE | -| `GeminiCLIExecutor` | Gêmeos CLI | Ciclo de atualização do token OAuth do Google | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Todos os outros provedores (incluindo nós compatíveis personalizados) usam `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matriz de compatibilidade do provedor +## Provider Compatibility Matrix -| Provedor | Formato | Autenticação | Transmitir | Não-transmissão | Atualização de token | API de uso | -| ------------------------ | ---------------- | --------------------------------- | ---------------- | --------------- | -------------------- | ------------------------ | -| Cláudio | Cláudio | Chave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Somente administrador | -| Gêmeos | gêmeos | Chave API/OAuth | ✅ | ✅ | ✅ | ⚠️Console em nuvem | -| Gêmeos CLI | gêmeo-cli | OAuth | ✅ | ✅ | ✅ | ⚠️Console em nuvem | -| Antigravidade | antigravidade | OAuth | ✅ | ✅ | ✅ | ✅ API de cota completa | -| OpenAI | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Códice | respostas openai | OAuth | ✅ forçado | ❌ | ✅ | ✅ Limites de taxas | -| Copiloto GitHub | abrirai | OAuth + token de copiloto | ✅ | ✅ | ✅ | ✅ Instantâneos de cota | -| Cursor | cursor | Soma de verificação personalizada | ✅ | ✅ | ❌ | ❌ | -| Kiro | Kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limites de uso | -| Qwen | abrirai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação | -| iFlow | abrirai | OAuth (Básico) | ✅ | ✅ | ✅ | ⚠️ Por solicitação | -| OpenRouter | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | Cláudio | Chave API | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Groq | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| xAI (Groque) | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Mistral | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Perplexidade | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Juntos IA | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| IA de fogos de artifício | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Cérebros | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| Coerente | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Cobertura de tradução de formato +## Format Translation Coverage -Os formatos de origem detectados incluem: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Os formatos de destino incluem: +Target formats include: -- Bate-papo/respostas OpenAI - -Cláudio -- Envelope Gemini/Gemini-CLI/Antigravidade - -Kiro +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro - Cursor -As traduções usam **OpenAI como formato de hub** — todas as conversões passam pelo OpenAI como intermediário: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -As traduções são selecionadas dinamicamente com base no formato da carga útil de origem e no formato de destino do provedor. +Translations are selected dynamically based on source payload shape and provider target format. -Camadas de processamento adicionais no pipeline de tradução: +Additional processing layers in the translation pipeline: -- **Sanitização de respostas** — Remove campos não padrão de respostas no formato OpenAI (streaming e não streaming) para garantir conformidade estrita com o SDK -- **Normalização de funções** — Converte `developer` → `system` para alvos não-OpenAI; mescla `system` → `user` para modelos que rejeitam a função do sistema (GLM, ERNIE) -- **Extração de tag Think** — Analisa blocos `...` do conteúdo no campo `reasoning_content` -- **Saída estruturada** — Converte OpenAI `response_format.json_schema` em `responseMimeType` + `responseSchema` do Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Terminais de API suportados +## Supported API Endpoints -| Ponto final | Formato | Manipulador | -| -------------------------------------------------- | ---------------------------- | -------------------------------------------------------------- | -| `POST /v1/chat/completions` | Bate-papo OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Mensagens de Cláudio | Mesmo manipulador (detectado automaticamente) | -| `POST /v1/responses` | Respostas OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Incorporações OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Listagem de modelos | Rota API | -| `POST /v1/images/generations` | Imagens OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Listagem de modelos | Rota API | -| `POST /v1/providers/{provider}/chat/completions` | Bate-papo OpenAI | Dedicado por provedor com validação de modelo | -| `POST /v1/providers/{provider}/embeddings` | Incorporações OpenAI | Dedicado por provedor com validação de modelo | -| `POST /v1/providers/{provider}/images/generations` | Imagens OpenAI | Dedicado por provedor com validação de modelo | -| `POST /v1/messages/count_tokens` | Contagem de tokens de Claude | Rota API | -| `GET /v1/models` | Lista de modelos OpenAI | Rota API (chat + incorporação + imagem + modelos customizados) | -| `GET /api/models/catalog` | Catálogo | Todos os modelos agrupados por fornecedor + tipo | -| `POST /v1beta/models/*:streamGenerateContent` | Nativo de Gêmeos | Rota API | -| `GET/PUT/DELETE /api/settings/proxy` | Configuração de proxy | Configuração de proxy de rede | -| `POST /api/settings/proxy/test` | Conectividade proxy | Endpoint de teste de integridade/conectividade do proxy | -| `GET/POST/DELETE /api/provider-models` | Modelos personalizados | Gestão de modelos customizados por provedor | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Ignorar manipulador +## Bypass Handler -O manipulador de bypass (`open-sse/utils/bypassHandler.ts`) intercepta solicitações "descartáveis" conhecidas da CLI de Claude — pings de aquecimento, extrações de títulos e contagens de tokens — e retorna uma **resposta falsa** sem consumir tokens do provedor upstream. Isso é acionado somente quando `User-Agent` contém `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Solicitar pipeline do registrador +## Request Logger Pipeline -O registrador de solicitações (`open-sse/utils/requestLogger.ts`) fornece um pipeline de registro de depuração de 7 estágios, desabilitado por padrão, habilitado por meio de `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Os arquivos são gravados em `/logs//` para cada sessão de solicitação. +Files are written to `/logs//` for each request session. -## Modos de falha e resiliência +## Failure Modes and Resilience -## 1) Disponibilidade da conta/provedor +## 1) Account/Provider Availability -- resfriamento da conta do provedor em erros transitórios/taxa/autenticação -- fallback da conta antes da falha na solicitação -- modelo combinado substituto quando o caminho do modelo/provedor atual se esgota +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Expiração do token +## 2) Token Expiry -- pré-verificação e atualização com nova tentativa para provedores atualizáveis -- Nova tentativa 401/403 após tentativa de atualização no caminho principal +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Segurança de transmissão +## 3) Stream Safety -- controlador de fluxo com reconhecimento de desconexão -- fluxo de tradução com liberação de fim de fluxo e manipulação de `[DONE]` -- fallback de estimativa de uso quando faltam metadados de uso do provedor +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Degradação da sincronização na nuvem +## 4) Cloud Sync Degradation -- erros de sincronização aparecem, mas o tempo de execução local continua -- o agendador tem lógica com capacidade de repetição, mas a execução periódica atualmente chama a sincronização de tentativa única por padrão +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integridade de dados +## 5) Data Integrity -- Migração/reparo de formato de banco de dados para chaves ausentes -- proteções de redefinição JSON corrompidas para localDb e usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Observabilidade e Sinais Operacionais +## Observability and Operational Signals -Fontes de visibilidade em tempo de execução: +Runtime visibility sources: -- registros do console de `src/sse/utils/logger.ts` -- agregados de uso por solicitação em `usage.json` -- registro de status da solicitação textual em `log.txt` -- registros opcionais de solicitação/tradução profunda em `logs/` quando `ENABLE_REQUEST_LOGS=true` -- endpoints de uso do painel (`/api/usage/*`) para consumo de UI +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Limites sensíveis à segurança +## Security-Sensitive Boundaries -- Segredo JWT (`JWT_SECRET`) protege a verificação/assinatura de cookies da sessão do painel -- O substituto de senha inicial (`INITIAL_PASSWORD`, padrão `123456`) deve ser substituído em implantações reais -- O segredo HMAC da chave de API (`API_KEY_SECRET`) protege o formato de chave de API local gerado -- Os segredos do provedor (chaves/tokens de API) persistem no banco de dados local e devem ser protegidos no nível do sistema de arquivos -- Os endpoints de sincronização em nuvem dependem da semântica de autenticação de chave de API + ID de máquina +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Matriz de Ambiente e Tempo de Execução +## Environment and Runtime Matrix -Variáveis de ambiente usadas ativamente pelo código: +Environment variables actively used by code: -- Aplicativo/autenticação: `JWT_SECRET`, `INITIAL_PASSWORD` -- Armazenamento: `DATA_DIR` -- Comportamento do nó compatível: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Substituição opcional da base de armazenamento (Linux/macOS quando `DATA_DIR` não definido): `XDG_CONFIG_HOME` -- Hash de segurança: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Registro: `ENABLE_REQUEST_LOGS` -- URL de sincronização/nuvem: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Proxy de saída: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` e variantes minúsculas -- Sinalizadores de recurso SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Auxiliares de plataforma/tempo de execução (não configuração específica do aplicativo): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Notas arquitetônicas conhecidas +## Known Architectural Notes -1. `usageDb` e `localDb` agora compartilham a mesma política de diretório base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) com migração de arquivo legado. -2. `/api/v1/route.ts` retorna uma lista de modelos estáticos e não é a principal fonte de modelos usada por `/v1/models`. -3. O registrador de solicitações grava cabeçalhos/corpo completos quando habilitado; trate o diretório de log como confidencial. -4. O comportamento da nuvem depende do `NEXT_PUBLIC_BASE_URL` correto e da acessibilidade do endpoint na nuvem. -5. O diretório `open-sse/` é publicado como o `@omniroute/open-sse` **pacote de espaço de trabalho npm**. O código-fonte o importa via `@omniroute/open-sse/...` (resolvido por Next.js `transpilePackages`). Os caminhos de arquivo neste documento ainda usam o nome de diretório `open-sse/` para consistência. -6. Os gráficos no painel usam **Recharts** (baseados em SVG) para visualizações analíticas interativas e acessíveis (gráficos de barras de uso de modelo, tabelas de detalhamento de fornecedores com taxas de sucesso). -7. Os testes E2E usam **Playwright** (`tests/e2e/`), executados via `npm run test:e2e`. Os testes de unidade usam o **executor de testes Node.js** (`tests/unit/`), executado por meio de `npm run test:plan3`. O código-fonte em `src/` é **TypeScript** (`.ts`/`.tsx`); o espaço de trabalho `open-sse/` permanece JavaScript (`.js`). -8. A página de configurações é organizada em 5 guias: Segurança, Roteamento (6 estratégias globais: preenchimento primeiro, round-robin, p2c, aleatório, menos usado, com custo otimizado), Resiliência (limites de taxa editáveis, disjuntor, políticas), IA (pensando no orçamento, prompt do sistema, cache de prompt), Avançado (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Lista de verificação de verificação operacional +## Operational Verification Checklist -- Construir a partir da fonte: `npm run build` -- Construir imagem Docker: `docker build -t omniroute .` -- Inicie o serviço e verifique: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- O URL base de destino da CLI deve ser `http://:20128/v1` quando `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/pt/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt/CODEBASE_DOCUMENTATION.md index 16693c3fb1..303880c198 100644 --- a/docs/i18n/pt/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/pt/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Documentação da base de código +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Um guia abrangente e para iniciantes sobre o roteador proxy AI multiprovedor **omniroute**. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. O que é OmniRoute? +## 1. What Is omniroute? -omniroute é um **roteador proxy** que fica entre clientes de IA (Claude CLI, Codex, Cursor IDE, etc.) e provedores de IA (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Isso resolve um grande problema: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Diferentes clientes de IA falam "idiomas" diferentes (formatos de API), e diferentes provedores de IA também esperam "idiomas" diferentes.** omniroute traduz entre eles automaticamente. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Pense nisso como um tradutor universal nas Nações Unidas – qualquer delegado pode falar qualquer idioma, e o tradutor converte para qualquer outro delegado. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Visão geral da arquitetura +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Princípio Básico: Tradução Hub-and-Spoke +### Core Principle: Hub-and-Spoke Translation -Toda a tradução de formato passa pelo **formato OpenAI como hub**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Isso significa que você só precisa de **N tradutores** (um por formato) em vez de **N²** (cada par). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Estrutura do Projeto +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Divisão módulo por módulo +## 4. Module-by-Module Breakdown -### 4.1 Configuração (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -A **única fonte de verdade** para todas as configurações do provedor. +The **single source of truth** for all provider configuration. -| Arquivo | Finalidade | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `constants.ts` | Objeto `PROVIDERS` com URLs base, credenciais OAuth (padrões), cabeçalhos e prompts de sistema padrão para cada provedor. Também define `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` e `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Carrega credenciais externas de `data/provider-credentials.json` e as mescla nos padrões codificados em `PROVIDERS`. Mantém os segredos fora do controle de origem, mantendo a compatibilidade com versões anteriores. | -| `providerModels.ts` | Registro central de modelos: aliases de provedores de mapas → IDs de modelos. Funções como `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Instruções do sistema injetadas em solicitações do Codex (restrições de edição, regras de sandbox, políticas de aprovação). | -| `defaultThinkingSignature.ts` | Assinaturas de "pensamento" padrão para os modelos Claude e Gemini. | -| `ollamaModels.ts` | Definição de esquema para modelos locais de Ollama (nome, tamanho, família, quantização). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Fluxo de carregamento de credenciais +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Executores (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Os executores encapsulam **lógica específica do provedor** usando o **Padrão de estratégia**. Cada executor substitui os métodos básicos conforme necessário. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Executor | Provedor | Principais Especializações | -| ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Base abstrata: construção de URL, cabeçalhos, lógica de repetição, atualização de credenciais | -| `default.ts` | Claude, Gêmeos, OpenAI, GLM, Kimi, MiniMax | Atualização genérica de token OAuth para provedores padrão | -| `antigravity.ts` | Código do Google Cloud | Geração de ID de projeto/sessão, fallback de vários URLs, análise de repetição personalizada de mensagens de erro ("redefinir após 2h7m23s") | -| `cursor.ts` | Cursor IDE | **Mais complexo**: autenticação de soma de verificação SHA-256, codificação de solicitação Protobuf, EventStream binário → análise de resposta SSE | -| `codex.ts` | Códice OpenAI | Injeta instruções do sistema, gerencia níveis de pensamento, remove parâmetros não suportados | -| `gemini-cli.ts` | CLI do Google Gemini | Criação de URL personalizado (`streamGenerateContent`), atualização de token Google OAuth | -| `github.ts` | Copiloto GitHub | Sistema de token duplo (token GitHub OAuth + Copilot), imitação de cabeçalho VSCode | -| `kiro.ts` | AWS CodeWhisperer | Análise binária AWS EventStream, event frames AMZN, estimativa de token | -| `index.ts` | — | Fábrica: nome do provedor de mapas → classe do executor, com fallback padrão | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Manipuladores (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -A **camada de orquestração** — coordena tradução, execução, streaming e tratamento de erros. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Arquivo | Finalidade | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Orquestrador central** (~600 linhas). Lida com o ciclo de vida completo da solicitação: detecção de formato → tradução → envio do executor → resposta de streaming/não streaming → atualização de token → tratamento de erros → registro de uso. | -| `responsesHandler.ts` | Adaptador para API de respostas da OpenAI: converte o formato de respostas → conclusões de bate-papo → envia para `chatCore` → converte SSE de volta para o formato de respostas. | -| `embeddings.ts` | Manipulador de geração de incorporação: resolve o modelo de incorporação → provedor, despacha para a API do provedor, retorna uma resposta de incorporação compatível com OpenAI. Suporta mais de 6 provedores. | -| `imageGeneration.ts` | Manipulador de geração de imagem: resolve modelo de imagem → provedor, suporta modos compatíveis com OpenAI, imagem Gemini (Antigravidade) e fallback (Nebius). Retorna imagens base64 ou URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Ciclo de vida da solicitação (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Serviços (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Lógica de negócios que dá suporte aos manipuladores e executores. +Business logic that supports the handlers and executors. -| Arquivo | Finalidade | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Detecção de formato** (`detectFormat`): analisa a estrutura do corpo da solicitação para identificar formatos Claude/OpenAI/Gemini/Antigravity/Responses (inclui heurística `max_tokens` para Claude). Além disso: construção de URL, construção de cabeçalho, normalização de configuração de pensamento. Suporta provedores dinâmicos `openai-compatible-*` e `anthropic-compatible-*`. | -| `model.ts` | Análise de string de modelo (`claude/model-name` → `{provider: "claude", model: "model-name"}`), resolução de alias com detecção de colisão, limpeza de entrada (rejeita caracteres de passagem/controle de caminho) e resolução de informações de modelo com suporte a getter de alias assíncrono. | -| `accountFallback.ts` | Tratamento de limite de taxa: espera exponencial (1s → 2s → 4s → máx. 2min), gerenciamento de resfriamento da conta, classificação de erros (quais erros acionam fallback versus não). | -| `tokenRefresh.ts` | Atualização de token OAuth para **todos os provedores**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Inclui cache de desduplicação de promessa em andamento e nova tentativa com espera exponencial. | -| `combo.ts` | **Modelos combinados**: cadeias de modelos alternativos. Se o modelo A falhar com um erro elegível para fallback, tente o modelo B, depois o C, etc. Retorna os códigos de status upstream reais. | -| `usage.ts` | Busca dados de cota/uso de APIs do provedor (cotas do GitHub Copilot, cotas do modelo antigravidade, limites de taxa do Codex, detalhamentos de uso do Kiro, configurações do Claude). | -| `accountSelector.ts` | Seleção inteligente de conta com algoritmo de pontuação: considera prioridade, status de integridade, posição round-robin e estado de espera para escolher a conta ideal para cada solicitação. | -| `contextManager.ts` | Gerenciamento do ciclo de vida do contexto de solicitação: cria e rastreia objetos de contexto por solicitação com metadados (ID da solicitação, carimbos de data/hora, informações do provedor) para depuração e registro em log. | -| `ipFilter.ts` | Controle de acesso baseado em IP: suporta modos de lista de permissões e lista de bloqueios. Valida o IP do cliente em relação às regras configuradas antes de processar solicitações de API. | -| `sessionManager.ts` | Rastreamento de sessão com impressão digital do cliente: rastreia sessões ativas usando identificadores de cliente com hash, monitora contagens de solicitações e fornece métricas de sessão. | -| `signatureCache.ts` | Solicitar cache de desduplicação baseado em assinatura: evita solicitações duplicadas armazenando em cache assinaturas de solicitações recentes e retornando respostas armazenadas em cache para solicitações idênticas dentro de um intervalo de tempo. | -| `systemPrompt.ts` | Injeção global de prompt do sistema: acrescenta ou acrescenta um prompt do sistema configurável a todas as solicitações, com tratamento de compatibilidade por provedor. | -| `thinkingBudget.ts` | Gerenciamento de orçamento de token de raciocínio: oferece suporte aos modos passthrough, automático (configuração de pensamento), personalizado (orçamento fixo) e adaptativo (escala de complexidade) para controlar tokens de pensamento/raciocínio. | -| `wildcardRouter.ts` | Roteamento de padrão de modelo curinga: resolve padrões curinga (por exemplo, `*/claude-*`) para pares concretos de provedor/modelo com base na disponibilidade e prioridade. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Desduplicação de atualização de token +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Máquina de estado substituto da conta +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Cadeia de modelos combinados +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Tradutor (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -O **mecanismo de tradução de formatos** usando um sistema de plugins com autorregistro. +The **format translation engine** using a self-registering plugin system. -#### Arquitetura +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Diretório | Arquivos | Descrição | -| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `request/` | 8 tradutores | Converta corpos de solicitação entre formatos. Cada arquivo é registrado automaticamente via `register(from, to, fn)` na importação. | -| `response/` | 7 tradutores | Converta pedaços de resposta de streaming entre formatos. Lida com tipos de eventos SSE, blocos de pensamento e chamadas de ferramentas. | -| `helpers/` | 6 ajudantes | Utilitários compartilhados: `claudeHelper` (extração de prompt do sistema, configuração de pensamento), `geminiHelper` (mapeamento de partes/conteúdo), `openaiHelper` (filtragem de formato), `toolCallHelper` (geração de ID, injeção de resposta ausente), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Mecanismo de tradução: `translateRequest()`, `translateResponse()`, gerenciamento de estado, registro. | -| `formats.ts` | — | Constantes de formato: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Design principal: plug-ins de autorregistro +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Utilitários (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Arquivo | Finalidade | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Criação de resposta a erros (formato compatível com OpenAI), análise de erros upstream, extração de tempo de repetição antigravidade de mensagens de erro, streaming de erros SSE. | -| `stream.ts` | **SSE Transform Stream** — o principal pipeline de streaming. Dois modos: `TRANSLATE` (tradução de formato completo) e `PASSTHROUGH` (normalizar + extrair uso). Lida com buffer de blocos, estimativa de uso e rastreamento de comprimento de conteúdo. As instâncias do codificador/decodificador por fluxo evitam o estado compartilhado. | -| `streamHelpers.ts` | Utilitários SSE de baixo nível: `parseSSELine` (tolerante a espaços em branco), `hasValuableContent` (filtra pedaços vazios para OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialização SSE com reconhecimento de formato com limpeza `perf_metrics`). | -| `usageTracking.ts` | Extração de uso de token de qualquer formato (Claude/OpenAI/Gemini/Responses), estimativa com proporções separadas de caracteres por ferramenta/mensagem por token, adição de buffer (margem de segurança de 2.000 tokens), filtragem de campo específica de formato, registro de console com cores ANSI. | -| `requestLogger.ts` | Registro de solicitação baseado em arquivo (aceitação via `ENABLE_REQUEST_LOGS=true`). Cria pastas de sessão com arquivos numerados: `1_req_client.json` → `7_res_client.txt`. Toda E/S é assíncrona (dispare e esqueça). Mascara cabeçalhos sensíveis. | -| `bypassHandler.ts` | Intercepta padrões específicos do Claude CLI (extração de título, aquecimento, contagem) e retorna respostas falsas sem ligar para nenhum provedor. Suporta streaming e não streaming. Intencionalmente limitado ao escopo Claude CLI. | -| `networkProxy.ts` | Resolve URL de proxy de saída para um determinado provedor com precedência: configuração específica do provedor → configuração global → variáveis ​​de ambiente (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Suporta exclusões `NO_PROXY`. Configuração de caches por 30s. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Pipeline de streaming SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Estrutura da sessão do registrador de solicitações +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Camada de Aplicação (`src/`) +### 4.7 Application Layer (`src/`) -| Diretório | Finalidade | -| ------------- | -------------------------------------------------------------------------------------- | -| `src/app/` | UI da Web, rotas de API, middleware Express, manipuladores de retorno de chamada OAuth | -| `src/lib/` | Acesso à base de dados (`localDb.ts`, `usageDb.ts`), autenticação, partilhada | -| `src/mitm/` | Utilitários proxy man-in-the-middle para interceptar o tráfego do provedor | -| `src/models/` | Definições de modelo de banco de dados | -| `src/shared/` | Wrappers em torno de funções open-sse (provedor, fluxo, erro, etc.) | -| `src/sse/` | Manipuladores de endpoint SSE que conectam a biblioteca open-sse às rotas Express | -| `src/store/` | Gerenciamento de estado de aplicação | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Rotas de API notáveis +#### Notable API Routes -| Rota | Métodos | Finalidade | -| --------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | -| `/api/provider-models` | OBTER/POSTAR/EXCLUIR | CRUD para modelos customizados por provedor | -| `/api/models/catalog` | OBTER | Catálogo agregado de todos os modelos (chat, incorporação, imagem, customizado) agrupados por provedor | -| `/api/settings/proxy` | OBTER/COLOCAR/EXCLUIR | Configuração hierárquica de proxy de saída (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POSTAR | Valida a conectividade do proxy e retorna IP público/latência | -| `/v1/providers/[provider]/chat/completions` | POSTAR | Conclusões de chat dedicadas por provedor com validação de modelo | -| `/v1/providers/[provider]/embeddings` | POSTAR | Incorporações dedicadas por provedor com validação de modelo | -| `/v1/providers/[provider]/images/generations` | POSTAR | Geração de imagens dedicadas por provedor com validação de modelo | -| `/api/settings/ip-filter` | OBTER/COLOCAR | Gerenciamento de lista de permissão/lista de bloqueio de IP | -| `/api/settings/thinking-budget` | OBTER/COLOCAR | Configuração do orçamento do token de raciocínio (passagem/automática/personalizada/adaptável) | -| `/api/settings/system-prompt` | OBTER/COLOCAR | Injeção imediata do sistema global para todas as solicitações | -| `/api/sessions` | OBTER | Acompanhamento e métricas de sessões ativas | -| `/api/rate-limits` | OBTER | Status do limite de taxa por conta | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Principais padrões de design +## 5. Key Design Patterns -### 5.1 Tradução Hub-and-Spoke +### 5.1 Hub-and-Spoke Translation -Todos os formatos são traduzidos através do **formato OpenAI como hub**. Adicionar um novo provedor requer apenas escrever **um par** de tradutores (de/para OpenAI), não N pares. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Padrão de Estratégia do Executor +### 5.2 Executor Strategy Pattern -Cada provedor possui uma classe de executor dedicada herdada de `BaseExecutor`. A fábrica em `executors/index.ts` seleciona o correto em tempo de execução. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Sistema de plug-ins de autorregistro +### 5.3 Self-Registering Plugin System -Os módulos tradutores se registram na importação via `register()`. Adicionar um novo tradutor é apenas criar um arquivo e importá-lo. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Fallback de conta com backoff exponencial +### 5.4 Account Fallback with Exponential Backoff -Quando um provedor retorna 429/401/500, o sistema pode mudar para a próxima conta, aplicando cooldowns exponenciais (1s → 2s → 4s → máx. 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Cadeias de modelos combinados +### 5.5 Combo Model Chains -Um "combo" agrupa várias strings `provider/model`. Se o primeiro falhar, volte para o próximo automaticamente. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Tradução de streaming com estado +### 5.6 Stateful Streaming Translation -A tradução de resposta mantém o estado em blocos SSE (rastreamento de blocos de pensamento, acúmulo de chamadas de ferramentas, indexação de blocos de conteúdo) por meio do mecanismo `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Buffer de segurança de uso +### 5.7 Usage Safety Buffer -Um buffer de 2.000 tokens é adicionado ao uso relatado para evitar que os clientes atinjam os limites da janela de contexto devido à sobrecarga dos prompts do sistema e da tradução de formato. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Formatos Suportados +## 6. Supported Formats -| Formato | Direção | Identificador | -| ------------------------------ | ---------------- | ------------------ | -| Conclusões do bate-papo OpenAI | origem + destino | `openai` | -| API de respostas OpenAI | origem + destino | `openai-responses` | -| Claude Antrópico | origem + destino | `claude` | -| Google Gêmeos | origem + destino | `gemini` | -| CLI do Google Gemini | apenas alvo | `gemini-cli` | -| Antigravidade | origem + destino | `antigravity` | -| AWSKiro | apenas alvo | `kiro` | -| Cursor | apenas alvo | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Provedores Suportados +## 7. Supported Providers -| Provedor | Método de autenticação | Executor | Notas principais | -| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------- | -| Claude Antrópico | Chave API ou OAuth | Padrão | Usa cabeçalho `x-api-key` | -| Google Gêmeos | Chave API ou OAuth | Padrão | Usa cabeçalho `x-goog-api-key` | -| CLI do Google Gemini | OAuth | GêmeosCLI | Usa ponto de extremidade `streamGenerateContent` | -| Antigravidade | OAuth | Antigravidade | Fallback de vários URLs, análise de repetição personalizada | -| OpenAI | Chave de API | Padrão | Autenticação do portador padrão | -| Códice | OAuth | Códice | Injeta instruções do sistema, gerencia o pensamento | -| Copiloto GitHub | Token OAuth + Copiloto | GitHub | Token duplo, imitação de cabeçalho VSCode | -| Kiro (AWS) | AWS SSO OIDC ou social | Kiro | Análise binária de EventStream | -| Cursor IDE | Autenticação de soma de verificação | Cursor | Codificação protobuf, somas de verificação SHA-256 | -| Qwen | OAuth | Padrão | Autenticação padrão | -| iFlow | OAuth (Básico + Portador) | Padrão | Cabeçalho de autenticação dupla | -| OpenRouter | Chave de API | Padrão | Autenticação do portador padrão | -| GLM, Kimi, MiniMax | Chave de API | Padrão | Compatível com Claude, use `x-api-key` | -| `openai-compatible-*` | Chave de API | Padrão | Dinâmico: qualquer endpoint compatível com OpenAI | -| `anthropic-compatible-*` | Chave de API | Padrão | Dinâmico: qualquer endpoint compatível com Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Resumo do fluxo de dados +## 8. Data Flow Summary -### Solicitação de streaming +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Solicitação de não streaming +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Desviar fluxo (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/pt/FEATURES.md b/docs/i18n/pt/FEATURES.md index 599e62469b..82cc73b67b 100644 --- a/docs/i18n/pt/FEATURES.md +++ b/docs/i18n/pt/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Galeria de recursos do painel +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Guia visual para cada seção do painel do OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Provedores +## 🔌 Providers -Gerencie conexões de provedores de IA: provedores OAuth (Claude Code, Codex, Gemini CLI), provedores de chaves de API (Groq, DeepSeek, OpenRouter) e provedores gratuitos (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨Combos +## 🎨 Combos -Crie combos de roteamento de modelos com 6 estratégias: preenchimento primeiro, round-robin, potência de duas opções, aleatório, menos usado e com custo otimizado. Cada combinação encadeia vários modelos com fallback automático. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Análise +## 📊 Analytics -Análise de uso abrangente com consumo de tokens, estimativas de custos, mapas de calor de atividades, gráficos de distribuição semanais e detalhamentos por provedor. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Saúde do Sistema +## 🏥 System Health -Monitoramento em tempo real: tempo de atividade, memória, versão, percentis de latência (p50/p95/p99), estatísticas de cache e estados de disjuntores do provedor. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Parque do Tradutor +## 🔧 Translator Playground -Quatro modos para depurar traduções de API: **Playground** (conversor de formato), **Chat Tester** (solicitações ao vivo), **Test Bench** (testes em lote) e **Live Monitor** (transmissão em tempo real). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Configurações +## 🎮 Model Playground _(v2.0.9+)_ -Configurações gerais, armazenamento do sistema, gerenciamento de backup (banco de dados de exportação/importação), aparência (modo escuro/claro), segurança (inclui proteção de endpoint de API e bloqueio de provedor personalizado), roteamento, resiliência e configuração avançada. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Ferramentas CLI +## 🔧 CLI Tools -Configuração com um clique para ferramentas de codificação de IA: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code e Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Solicitar registros +## 🤖 CLI Agents _(v2.0.11+)_ -Registro de solicitações em tempo real com filtragem por provedor, modelo, conta e chave de API. Mostra códigos de status, uso de token, latência e detalhes de resposta. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Ponto final da API +## 🌐 API Endpoint -Seu endpoint de API unificado com detalhamento de recursos: conclusões de bate-papo, incorporações, geração de imagens, reclassificação, transcrição de áudio e chaves de API registradas. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/pt/TROUBLESHOOTING.md b/docs/i18n/pt/TROUBLESHOOTING.md index 5066922892..120092d63c 100644 --- a/docs/i18n/pt/TROUBLESHOOTING.md +++ b/docs/i18n/pt/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Solução de problemas +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Problemas e soluções comuns para OmniRoute. +Common problems and solutions for OmniRoute. --- -## Correções rápidas +## Quick Fixes -| Problema | Solução | -| ----------------------------------------- | -------------------------------------------------------------------------------------- | -| O primeiro login não funciona | Verifique `INITIAL_PASSWORD` em `.env` (padrão: `123456`) | -| Painel abre na porta errada | Definir `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Nenhum registro de solicitação em `logs/` | Definir `ENABLE_REQUEST_LOGS=true` | -| EACCES: permissão negada | Defina `DATA_DIR=/path/to/writable/dir` para substituir `~/.omniroute` | -| Estratégia de roteamento não salva | Atualização para v1.4.11+ (correção do esquema Zod para persistência de configurações) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Problemas do provedor +## Provider Issues -### "O modelo de linguagem não forneceu mensagens" +### "Language model did not provide messages" -**Causa:** Cota do provedor esgotada. +**Cause:** Provider quota exhausted. -**Correção:** +**Fix:** -1. Verifique o rastreador de cota do painel -2. Use um combo com níveis alternativos -3. Mude para um nível mais barato/gratuito +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Limitação de taxa +### Rate Limiting -**Causa:** Cota de assinatura esgotada. +**Cause:** Subscription quota exhausted. -**Correção:** +**Fix:** -- Adicionar substituto: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Use GLM/MiniMax como backup barato +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Token OAuth expirado +### OAuth Token Expired -OmniRoute atualiza automaticamente os tokens. Se os problemas persistirem: +OmniRoute auto-refreshes tokens. If issues persist: -1. Painel → Provedor → Reconectar -2. Exclua e adicione novamente a conexão do provedor +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Problemas de nuvem +## Cloud Issues -### Erros de sincronização na nuvem +### Cloud Sync Errors -1. Verifique `BASE_URL` aponta para sua instância em execução (por exemplo, `http://localhost:20128`) -2. Verifique os pontos `CLOUD_URL` para seu endpoint de nuvem (por exemplo, `https://omniroute.dev`) -3. Mantenha os valores `NEXT_PUBLIC_*` alinhados com os valores do lado do servidor +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Nuvem `stream=false` Retorna 500 +### Cloud `stream=false` Returns 500 -**Sintoma:** `Unexpected token 'd'...` no endpoint da nuvem para chamadas sem streaming. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Causa:** O upstream retorna a carga SSE enquanto o cliente espera JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Solução alternativa:** use `stream=true` para chamadas diretas na nuvem. O tempo de execução local inclui substituto SSE→JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud diz conectado, mas "chave de API inválida" +### Cloud Says Connected but "Invalid API key" -1. Crie uma nova chave no painel local (`/api/keys`) -2. Execute a sincronização na nuvem: Habilite Nuvem → Sincronizar agora -3. Chaves antigas/não sincronizadas ainda podem retornar `401` na nuvem +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Problemas do Docker +## Docker Issues -### A ferramenta CLI mostra não instalada +### CLI Tool Shows Not Installed -1. Verifique os campos de tempo de execução: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Para modo portátil: use o destino de imagem `runner-cli` (CLIs agrupados) -3. Para o modo de montagem do host: defina `CLI_EXTRA_PATHS` e monte o diretório bin do host como somente leitura -4. Se `installed=true` e `runnable=false`: o binário foi encontrado, mas falhou na verificação de integridade +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Validação Rápida de Tempo de Execução +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Problemas de custo +## Cost Issues -### Custos elevados +### High Costs -1. Verifique as estatísticas de uso em Painel → Uso -2. Mude o modelo primário para GLM/MiniMax -3. Use o nível gratuito (Gemini CLI, iFlow) para tarefas não críticas -4. Defina orçamentos de custos por chave de API: Painel → Chaves de API → Orçamento +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Depuração +## Debugging -### Habilitar registros de solicitação +### Enable Request Logs -Defina `ENABLE_REQUEST_LOGS=true` em seu arquivo `.env`. Os logs aparecem no diretório `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Verifique a integridade do provedor +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Armazenamento em tempo de execução +### Runtime Storage -- Estado principal: `${DATA_DIR}/db.json` (provedores, combos, aliases, chaves, configurações) -- Uso: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Registros de solicitação: `/logs/...` (quando `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Problemas com disjuntores +## Circuit Breaker Issues -### Provedor preso no estado OPEN +### Provider stuck in OPEN state -Quando o disjuntor de um provedor está ABERTO, as solicitações são bloqueadas até que o tempo de espera expire. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Correção:** +**Fix:** -1. Vá para **Painel → Configurações → Resiliência** -2. Verifique a placa do disjuntor do provedor afetado -3. Clique em **Redefinir tudo** para limpar todos os disjuntores ou aguarde o tempo de espera expirar -4. Verifique se o provedor está realmente disponível antes de redefinir +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### O provedor continua desarmando o disjuntor +### Provider keeps tripping the circuit breaker -Se um provedor entrar repetidamente no estado OPEN: +If a provider repeatedly enters OPEN state: -1. Verifique **Dashboard → Health → Provider Health** para ver o padrão de falha -2. Vá para **Configurações → Resiliência → Perfis do Provedor** e aumente o limite de falha -3. Verifique se o provedor alterou os limites da API ou requer nova autenticação -4. Revise a telemetria de latência – alta latência pode causar falhas baseadas em tempo limite +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problemas de transcrição de áudio +## Audio Transcription Issues -### Erro "Modelo não suportado" +### "Unsupported model" error -- Certifique-se de usar o prefixo correto: `deepgram/nova-3` ou `assemblyai/best` -- Verifique se o provedor está conectado em **Painel → Provedores** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### A transcrição retorna vazia ou falha +### Transcription returns empty or fails -- Verifique os formatos de áudio suportados: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Verifique se o tamanho do arquivo está dentro dos limites do provedor (normalmente <25 MB) -- Verifique a validade da chave API do provedor no cartão do provedor +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Depuração do tradutor +## Translator Debugging -Use **Dashboard → Tradutor** para depurar problemas de tradução de formato: +Use **Dashboard → Translator** to debug format translation issues: -| Modo | Quando usar | -| ------------------------- | --------------------------------------------------------------------------------------------------------------- | -| **Parque Infantil** | Compare os formatos de entrada/saída lado a lado — cole uma solicitação com falha para ver como ela é traduzida | -| **Testador de bate-papo** | Envie mensagens ao vivo e inspecione a carga completa de solicitação/resposta, incluindo cabeçalhos | -| **Banco de testes** | Execute testes em lote em combinações de formatos para descobrir quais traduções estão quebradas | -| **Monitoramento ao vivo** | Observe o fluxo de solicitações em tempo real para detectar problemas intermitentes de tradução | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Problemas comuns de formato +### Common format issues -- **Tags de pensamento não aparecem** — Verifique se o provedor alvo apoia o pensamento e a configuração do orçamento de pensamento -- **Queda de chamadas de ferramentas** — Algumas traduções de formato podem remover campos não suportados; verificar no modo Playground -- **Prompt do sistema ausente** — Claude e Gemini lidam com os prompts do sistema de maneira diferente; verifique o resultado da tradução -- **SDK retorna string bruta em vez de objeto** — Corrigido na v1.1.0: o sanitizador de resposta agora remove campos não padrão (`x_groq`, `usage_breakdown`, etc.) que causam falhas de validação do OpenAI SDK Pydantic -- **GLM/ERNIE rejeita função `system`** — Corrigido na v1.1.0: o normalizador de função mescla automaticamente mensagens do sistema em mensagens do usuário para modelos incompatíveis -- Função **`developer` não reconhecida** — Corrigido na v1.1.0: convertido automaticamente para `system` para provedores não-OpenAI -- **`json_schema` não funciona com Gemini** — Corrigido na v1.1.0: `response_format` agora é convertido para `responseMimeType` + `responseSchema` do Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Configurações de resiliência +## Resilience Settings -### Limite de taxa automático não acionado +### Auto rate-limit not triggering -- O limite automático de taxa se aplica apenas a provedores de chaves de API (não a OAuth/assinatura) -- Verifique se **Configurações → Resiliência → Perfis do Provedor** tem limite de taxa automática ativado -- Verifique se o provedor retorna códigos de status `429` ou cabeçalhos `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Ajustando a espera exponencial +### Tuning exponential backoff -Os perfis do provedor oferecem suporte a estas configurações: +Provider profiles support these settings: -- **Atraso base** — Tempo de espera inicial após a primeira falha (padrão: 1s) -- **Atraso máximo** — Limite máximo de tempo de espera (padrão: 30s) -- **Multiplicador** — Quanto aumentar o atraso por falha consecutiva (padrão: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Rebanho anti-trovão +### Anti-thundering herd -Quando muitas solicitações simultâneas atingem um provedor com taxa limitada, o OmniRoute usa mutex + limitação automática de taxa para serializar solicitações e evitar falhas em cascata. Isso é automático para provedores de chaves de API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Ainda preso? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Problemas do GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arquitetura**: Consulte [link](ARCHITECTURE.md) para detalhes internos -- **Referência da API**: Consulte [link](API_REFERENCE.md) para todos os endpoints -- **Painel de saúde**: verifique **Painel → Saúde** para ver o status do sistema em tempo real -- **Tradutor**: Use **Dashboard → Tradutor** para depurar problemas de formato +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/pt/USER_GUIDE.md b/docs/i18n/pt/USER_GUIDE.md index d1a6876022..5a043224df 100644 --- a/docs/i18n/pt/USER_GUIDE.md +++ b/docs/i18n/pt/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Guia do usuário +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Guia completo para configurar provedores, criar combos, integrar ferramentas CLI e implantar OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Índice +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Guia completo para configurar provedores, criar combos, integrar ferramentas CLI --- -## 💰 Visão geral dos preços +## 💰 Pricing at a Glance -| Nível | Provedor | Custo | Redefinição de cota | Melhor para | -| ------------------- | ------------------------ | ---------------- | ------------------------ | ----------------------------- | -| **💳 ASSINATURA** | Código Claude (Pro) | $ 20/mês | 5h + semanalmente | Já inscrito | -| | Códice (Plus/Pro) | US$ 20-200/mês | 5h + semanalmente | Usuários OpenAI | -| | Gêmeos CLI | **GRÁTIS** | 180 mil/mês + 1 mil/dia | Todos! | -| | Copiloto GitHub | US$ 10-19/mês | Mensalmente | Usuários do GitHub | -| **🔑 CHAVE DE API** | DeepSeek | Pague por uso | Nenhum | Raciocínio barato | -| | Groq | Pague por uso | Nenhum | Inferência ultrarrápida | -| | xAI (Groque) | Pague por uso | Nenhum | Raciocínio Grok 4 | -| | Mistral | Pague por uso | Nenhum | Modelos hospedados na UE | -| | Perplexidade | Pague por uso | Nenhum | Pesquisa aumentada | -| | Juntos IA | Pague por uso | Nenhum | Modelos de código aberto | -| | IA de fogos de artifício | Pague por uso | Nenhum | Imagens FLUX rápidas | -| | Cérebros | Pague por uso | Nenhum | Velocidade em escala de wafer | -| | Coerente | Pague por uso | Nenhum | Comando R+ RAG | -| | NVIDIA NIM | Pague por uso | Nenhum | Modelos empresariais | -| **💰 BARATO** | GLM-4.7 | US$ 0,6/1 milhão | Diariamente 10h | Backup de orçamento | -| | MiniMax M2.1 | US$ 0,2/1 milhão | Rolamento de 5 horas | Opção mais barata | -| | Kimi K2 | $ 9 / mês fixo | 10 milhões de tokens/mês | Custo previsível | -| **🆓 GRÁTIS** | iFlow | $0 | Ilimitado | 8 modelos grátis | -| | Qwen | $0 | Ilimitado | 3 modelos grátis | -| | Kiro | $0 | Ilimitado | Cláudio grátis | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Dica profissional:** Comece com Gemini CLI (180 mil grátis/mês) + combo iFlow (gratuito ilimitado) = custo de $ 0! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Casos de uso +## 🎯 Use Cases -### Caso 1: "Tenho assinatura do Claude Pro" +### Case 1: "I have Claude Pro subscription" -**Problema:** A cota expira sem ser utilizada, limites de taxa durante codificação pesada +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Caso 2: "Quero custo zero" +### Case 2: "I want zero cost" -**Problema:** Não posso pagar assinaturas, preciso de codificação de IA confiável +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Caso 3: "Preciso de codificação 24 horas por dia, 7 dias por semana, sem interrupções" +### Case 3: "I need 24/7 coding, no interruptions" -**Problema:** Prazos, não podemos arcar com o tempo de inatividade +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Caso 4: "Quero IA GRATUITA no OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Problema:** Precisa de assistente de IA em aplicativos de mensagens, totalmente gratuito +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Configuração do provedor +## 📖 Provider Setup -### 🔐 Provedores de assinatura +### 🔐 Subscription Providers -#### Código Claude (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Dica profissional:** Use o Opus para tarefas complexas e o Sonnet para velocidade. OmniRoute rastreia cota por modelo! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (GRÁTIS 180 mil/mês!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Melhor valor:** Grande nível gratuito! Use isso antes dos níveis pagos. +**Best Value:** Huge free tier! Use this before paid tiers. -#### GitHub Copiloto +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Fornecedores baratos +### 💰 Cheap Providers -#### GLM-4.7 (redefinição diária, US$ 0,6/1 milhão) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Inscreva-se: [Zhipu AI](https://open.bigmodel.cn/) -2. Obtenha a chave API do plano de codificação -3. Painel → Adicionar chave de API: Provedor: `glm`, chave de API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Usar:** `glm/glm-4.7` — **Dica profissional:** O plano de codificação oferece 3× cota a 1/7 de custo! Redefinir diariamente às 10h. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (redefinição de 5h, US$ 0,20/1 milhão) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Inscreva-se: [MiniMax](https://www.minimax.io/) -2. Obter chave de API → Painel → Adicionar chave de API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Use:** `minimax/MiniMax-M2.1` — **Dica profissional:** Opção mais barata para contexto longo (1 milhão de tokens)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (US$ 9/mês fixo) +#### Kimi K2 ($9/month flat) -1. Inscreva-se: [Moonshot AI](https://platform.moonshot.ai/) -2. Obter chave de API → Painel → Adicionar chave de API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Uso:** `kimi/kimi-latest` — **Dica profissional:** Fixo US$ 9/mês para 10 milhões de tokens = US$ 0,90/1 milhão de custo efetivo! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 Provedores GRATUITOS +### 🆓 FREE Providers -#### iFlow (8 modelos GRATUITOS) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 modelos GRATUITOS) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRÁTIS) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨Combos +## 🎨 Combos -### Exemplo 1: Maximize a assinatura → Backup barato +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Exemplo 2: somente gratuito (custo zero) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,7 +249,7 @@ Cost: $0 forever! --- -## 🔧 Integração CLI +## 🔧 CLI Integration ### Cursor IDE @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Código Cláudio +### Claude Code -Editar `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Editar `~/.claude/config.json`: } ``` -### CLI do Codex +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -279,9 +279,9 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -###OpenClaw +### OpenClaw -Editar `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Editar `~/.openclaw/openclaw.json`: } ``` -**Ou use o Dashboard:** Ferramentas CLI → OpenClaw → Configuração automática +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Continuar / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Implantação +## 🚀 Deployment -### Implantação VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Para o modo integrado ao host com binários CLI, consulte a seção Docker na documentação principal. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Variáveis de Ambiente +### Environment Variables -| Variável | Padrão | Descrição | -| --------------------- | ------------------------------------ | --------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Segredo de assinatura do JWT (**mudança na produção**) | -| `INITIAL_PASSWORD` | `123456` | Senha do primeiro login | -| `DATA_DIR` | `~/.omniroute` | Diretório de dados (banco de dados, uso, logs) | -| `PORT` | padrão da estrutura | Porta de serviço (`20128` em exemplos) | -| `HOSTNAME` | padrão da estrutura | Host de vinculação (o padrão do Docker é `0.0.0.0`) | -| `NODE_ENV` | padrão de tempo de execução | Definir `production` para implantação | -| `BASE_URL` | `http://localhost:20128` | URL base interna do lado do servidor | -| `CLOUD_URL` | `https://omniroute.dev` | URL base do endpoint de sincronização em nuvem | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Segredo HMAC para chaves de API geradas | -| `REQUIRE_API_KEY` | `false` | Aplicar chave de API do portador em `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Habilita registros de solicitação/resposta | -| `AUTH_COOKIE_SECURE` | `false` | Forçar cookie de autenticação `Secure` (atrás do proxy reverso HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Para obter a referência completa da variável de ambiente, consulte [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Modelos Disponíveis +## 📊 Available Models
-Ver todos os modelos disponíveis +View all available models -**Código Claude (`cc/`)** — Pro/Máx: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Códice (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATUITO: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Copiloto do GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — US$ 0,6/1 milhão: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — US$ 0,2/1 milhão: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATUITO: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATUITO: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATUITO: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,15 +460,15 @@ Para obter a referência completa da variável de ambiente, consulte [README](.. **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Perplexidade (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Juntos AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**IA do Fireworks (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Cérebros (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Coerente (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ Para obter a referência completa da variável de ambiente, consulte [README](.. --- -## 🧩 Recursos avançados +## 🧩 Advanced Features -### Modelos personalizados +### Custom Models -Adicione qualquer ID de modelo a qualquer provedor sem esperar por uma atualização do aplicativo: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Ou use o Dashboard: **Provedores → [Provedor] → Modelos personalizados**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Rotas de provedores dedicados +### Dedicated Provider Routes -Encaminhe solicitações diretamente para um provedor específico com validação de modelo: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -O prefixo do provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Configuração de proxy de rede +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Precedência:** Específico da chave → Específico do combo → Específico do provedor → Global → Ambiente. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API de catálogo de modelos +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Retorna modelos agrupados por provedor com tipos (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Sincronização na nuvem +### Cloud Sync -- Sincronize provedores, combos e configurações entre dispositivos -- Sincronização automática em segundo plano com tempo limite + falha rápida -- Prefira `BASE_URL`/`CLOUD_URL` do lado do servidor na produção +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (Fase 9) +### LLM Gateway Intelligence (Phase 9) -- **Cache Semântico** — Armazena automaticamente em cache sem streaming, temperatura = 0 respostas (ignorar com `X-OmniRoute-No-Cache: true`) -- **Idempotência de solicitação** — Desduplica solicitações em 5s por meio do cabeçalho `Idempotency-Key` ou `X-Request-Id` -- **Acompanhamento de progresso** — Eventos SSE `event: progress` de aceitação por meio do cabeçalho `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Parque do Tradutor +### Translator Playground -Acesso via **Painel → Tradutor**. Depure e visualize como o OmniRoute traduz solicitações de API entre provedores. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Modo | Finalidade | -| ------------------------- | ----------------------------------------------------------------------------------------------------------- | -| **Parque Infantil** | Selecione os formatos de origem/destino, cole uma solicitação e veja o resultado traduzido instantaneamente | -| **Testador de bate-papo** | Envie mensagens de chat ao vivo através do proxy e inspecione todo o ciclo de solicitação/resposta | -| **Banco de testes** | Execute testes em lote em múltiplas combinações de formatos para verificar a exatidão da tradução | -| **Monitoramento ao vivo** | Assista às traduções em tempo real enquanto as solicitações fluem pelo proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Casos de uso:** +**Use cases:** -- Depure por que uma combinação específica de cliente/provedor falha -- Verifique se as tags de pensamento, as chamadas de ferramentas e os prompts do sistema são traduzidos corretamente -- Compare as diferenças de formato entre os formatos OpenAI, Claude, Gemini e Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Estratégias de roteamento +### Routing Strategies -Configure via **Painel → Configurações → Roteamento**. +Configure via **Dashboard → Settings → Routing**. -| Estratégia | Descrição | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| **Preencha primeiro** | Usa contas em ordem de prioridade – a conta principal lida com todas as solicitações até ficar indisponível | -| **Round Robin** | Percorre todas as contas com um limite fixo configurável (padrão: 3 chamadas por conta) | -| **P2C (Poder de Duas Escolhas)** | Escolhe 2 contas aleatórias e direciona para a mais saudável — equilibra a carga com a consciência da saúde | -| **Aleatório** | Seleciona aleatoriamente uma conta para cada solicitação usando o embaralhamento Fisher-Yates | -| **Menos usado** | Roteia para a conta com o carimbo de data/hora `lastUsedAt` mais antigo, distribuindo o tráfego uniformemente | -| **Custo Otimizado** | Rotas para a conta com menor valor de prioridade, otimizando para provedores de menor custo | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Aliases de modelo curinga +#### Wildcard Model Aliases -Crie padrões curinga para remapear nomes de modelos: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Os curingas suportam `*` (qualquer caractere) e `?` (caractere único). +Wildcards support `*` (any characters) and `?` (single character). -#### Cadeias substitutas +#### Fallback Chains -Defina cadeias de fallback globais que se aplicam a todas as solicitações: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Resiliência e Disjuntores +### Resilience & Circuit Breakers -Configure via **Painel → Configurações → Resiliência**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementa resiliência em nível de provedor com quatro componentes: +OmniRoute implements provider-level resilience with four components: -1. **Perfis de Provedores** — Configuração por provedor para: - - Limite de falha (quantas falhas antes da abertura) - - Duração do resfriamento - - Sensibilidade de detecção de limite de taxa - - Parâmetros de espera exponencial +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Limites de taxa editáveis** — Padrões de nível de sistema configuráveis no painel: - - **Solicitações por minuto (RPM)** — Máximo de solicitações por minuto por conta - - **Tempo mínimo entre solicitações** — Intervalo mínimo em milissegundos entre solicitações - - **Máximo de solicitações simultâneas** — Máximo de solicitações simultâneas por conta - - Clique em **Editar** para modificar e depois em **Salvar** ou **Cancelar**. Os valores persistem por meio da API de resiliência. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Disjuntor** — Rastreia falhas por provedor e abre automaticamente o circuito quando um limite é atingido: - - **FECHADO** (Saudável) — As solicitações fluem normalmente - - **OPEN** — O provedor é bloqueado temporariamente após falhas repetidas - - **HALF_OPEN** — Testando se o provedor se recuperou +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Políticas e identificadores bloqueados** — Mostra o status do disjuntor e identificadores bloqueados com capacidade de desbloqueio forçado. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Detecção automática de limite de taxa** — Monitora os cabeçalhos `429` e `Retry-After` para evitar proativamente atingir os limites de taxa do provedor. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Dica profissional:** Use o botão **Redefinir tudo** para limpar todos os disjuntores e resfriamentos quando um provedor se recupera de uma interrupção. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Exportação/Importação de banco de dados +### Database Export / Import -Gerencie backups de banco de dados em **Painel → Configurações → Sistema e armazenamento**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Ação | Descrição | -| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Exportar banco de dados** | Baixa o banco de dados SQLite atual como um arquivo `.sqlite` | -| **Exportar tudo (.tar.gz)** | Baixa um arquivo de backup completo, incluindo: banco de dados, configurações, combos, conexões de provedor (sem credenciais), metadados de chave API | -| **Importar banco de dados** | Faça upload de um arquivo `.sqlite` para substituir o banco de dados atual. Um backup de pré-importação é criado automaticamente | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Validação de importação:** O arquivo importado é validado quanto à integridade (verificação de pragma SQLite), tabelas necessárias (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) e tamanho (máximo de 100 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Casos de uso:** +**Use Cases:** -- Migrar OmniRoute entre máquinas -- Crie backups externos para recuperação de desastres -- Compartilhe configurações entre membros da equipe (exportar tudo → compartilhar arquivo) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Painel de configurações +### Settings Dashboard -A página de configurações está organizada em 5 guias para facilitar a navegação: +The settings page is organized into 5 tabs for easy navigation: -| Guia | Conteúdo | -| --------------- | ----------------------------------------------------------------------------------------------------------------- | -| **Segurança** | Configurações de login/senha, controle de acesso IP, autenticação de API para `/models` e bloqueio de provedor | -| **Roteamento** | Estratégia de roteamento global (6 opções), aliases de modelo curinga, cadeias de fallback, padrões de combinação | -| **Resiliência** | Perfis de provedores, limites de taxas editáveis, status de disjuntores, políticas e identificadores bloqueados | -| **IA** | Pensando na configuração do orçamento, injeção de prompt do sistema global, estatísticas de cache de prompt | -| **Avançado** | Configuração de proxy global (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Gestão de Custos e Orçamento +### Costs & Budget Management -Acesso via **Painel → Custos**. +Access via **Dashboard → Costs**. -| Guia | Finalidade | -| ------------- | -------------------------------------------------------------------------------------------------------------- | -| **Orçamento** | Defina limites de gastos por chave de API com orçamentos diários/semanais/mensais e rastreamento em tempo real | -| **Preços** | Visualize e edite entradas de preços de modelo — custo por 1 mil tokens de entrada/saída por provedor | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Acompanhamento de custos:** cada solicitação registra o uso do token e calcula o custo usando a tabela de preços. Veja detalhes em **Painel → Uso** por provedor, modelo e chave de API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Transcrição de áudio +### Audio Transcription -OmniRoute oferece suporte à transcrição de áudio por meio do endpoint compatível com OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Provedores disponíveis: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Formatos de áudio suportados: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Estratégias de balanceamento de combinação +### Combo Balancing Strategies -Configure o balanceamento por combo em **Painel → Combos → Criar/Editar → Estratégia**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Estratégia | Descrição | -| ------------------- | ----------------------------------------------------------------------------------------- | -| **Round-Robin** | Gira pelos modelos sequencialmente | -| **Prioridade** | Tenta sempre o primeiro modelo; recorre apenas ao erro | -| **Aleatório** | Escolhe um modelo aleatório do combo para cada solicitação | -| **Ponderada** | Rotas proporcionalmente com base nos pesos atribuídos por modelo | -| **Menos usado** | Rotas para o modelo com o menor número de solicitações recentes (usa métricas combinadas) | -| **Custo Otimizado** | Rotas para o modelo mais barato disponível (usa tabela de preços) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Os padrões de combinação global podem ser definidos em **Painel → Configurações → Roteamento → Padrões de combinação**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Painel de saúde +### Health Dashboard -Acesso via **Painel → Saúde**. Visão geral da integridade do sistema em tempo real com 6 cartões: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Cartão | O que mostra | -| -------------------------- | ----------------------------------------------------------------------- | -| **Status do sistema** | Tempo de atividade, versão, uso de memória, diretório de dados | -| **Provedor de Saúde** | Estado do disjuntor por fornecedor (Fechado/Aberto/Meio-aberto) | -| **Limites de Tarifas** | Cooldowns de limite de taxa ativa por conta com tempo restante | -| **Bloqueios ativos** | Prestadores bloqueados temporariamente pela política de lockout | -| **Cache de Assinaturas** | Estatísticas do cache de desduplicação (chaves ativas, taxa de acertos) | -| **Telemetria de latência** | Agregação de latência p50/p95/p99 por provedor | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Dica profissional:** a página Saúde é atualizada automaticamente a cada 10 segundos. Use a placa do disjuntor para identificar quais provedores estão enfrentando problemas. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/ro/API_REFERENCE.md b/docs/i18n/ro/API_REFERENCE.md index d9bf96d0db..b795722c11 100644 --- a/docs/i18n/ro/API_REFERENCE.md +++ b/docs/i18n/ro/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Referință API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Referință completă pentru toate punctele finale API OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Cuprins +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Referință completă pentru toate punctele finale API OmniRoute. --- -## Finalizări de chat +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Anteturi personalizate +### Custom Headers -| Antet | Direcție | Descriere | -| ------------------------ | -------- | ----------------------------------------------- | -| `X-OmniRoute-No-Cache` | Cerere | Setați la `true` pentru a ocoli memoria cache | -| `X-OmniRoute-Progress` | Cerere | Setați la `true` pentru evenimentele de progres | -| `Idempotency-Key` | Cerere | Tasta Dedup (fereastră 5s) | -| `X-Request-Id` | Cerere | Cheie alternativă de deducție | -| `X-OmniRoute-Cache` | Răspuns | `HIT` sau `MISS` (non-streaming) | -| `X-OmniRoute-Idempotent` | Răspuns | `true` dacă este deduplicat | -| `X-OmniRoute-Progress` | Răspuns | `enabled` dacă urmărirea progresului pe | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Înglobări +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Furnizori disponibili: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Generare de imagini +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Furnizori disponibili: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Listează modele +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Puncte finale de compatibilitate +## Compatibility Endpoints -| Metoda | Calea | Format | -| ------ | --------------------------- | ------------------------ | -| POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | antropic | -| POST | `/v1/responses` | Răspunsuri OpenAI | -| POST | `/v1/embeddings` | OpenAI | -| POST | `/v1/images/generations` | OpenAI | -| GET | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | antropic | -| GET | `/v1beta/models` | Gemeni | -| POST | `/v1beta/models/{...path}` | Gemeni genereazăConținut | -| POST | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Rute de furnizori dedicate +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Prefixul furnizorului este adăugat automat dacă lipsește. Modelele nepotrivite revin `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Cache semantic +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Exemplu de răspuns: +Response example: ```json { @@ -162,154 +162,164 @@ Exemplu de răspuns: --- -## Tabloul de bord și managementul +## Dashboard & Management -### Autentificare +### Authentication -| Punct final | Metoda | Descriere | -| ----------------------------- | ------- | ------------------------------- | -| `/api/auth/login` | POST | Autentificare | -| `/api/auth/logout` | POST | Deconectare | -| `/api/settings/require-login` | GET/PUT | Comutare autentificare necesară | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Managementul furnizorilor +### Provider Management -| Punct final | Metoda | Descriere | -| ---------------------------- | --------------- | ---------------------------------- | -| `/api/providers` | GET/POST | Listează / creează furnizori | -| `/api/providers/[id]` | GET/PUT/DELETE | Gestionați un furnizor | -| `/api/providers/[id]/test` | POST | Testează conexiunea furnizorului | -| `/api/providers/[id]/models` | GET | Listați modele de furnizori | -| `/api/providers/validate` | POST | Validați configurația furnizorului | -| `/api/provider-nodes*` | Diverse | Gestionarea nodurilor furnizorului | -| `/api/provider-models` | GET/POST/DELETE | Modele personalizate | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Fluxuri OAuth +### OAuth Flows -| Punct final | Metoda | Descriere | -| -------------------------------- | ------- | --------------------------- | -| `/api/oauth/[provider]/[action]` | Diverse | OAuth specific furnizorului | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Rutare și configurare +### Routing & Config -| Punct final | Metoda | Descriere | -| --------------------- | -------- | ---------------------------------- | -| `/api/models/alias` | GET/POST | Aliasuri de model | -| `/api/models/catalog` | GET | Toate modelele după furnizor + tip | -| `/api/combos*` | Diverse | Combo management | -| `/api/keys*` | Diverse | Gestionarea cheilor API | -| `/api/pricing` | GET | Prețul modelului | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Utilizare și analiză +### Usage & Analytics -| Punct final | Metoda | Descriere | -| --------------------------- | ------ | ---------------------------- | -| `/api/usage/history` | GET | Istoricul utilizării | -| `/api/usage/logs` | GET | Jurnalele de utilizare | -| `/api/usage/request-logs` | GET | Jurnalele la nivel de cerere | -| `/api/usage/[connectionId]` | GET | Utilizare per conexiune | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Setări +### Settings -| Punct final | Metoda | Descriere | -| ------------------------------- | ------- | ------------------------------ | -| `/api/settings` | GET/PUT | Setări generale | -| `/api/settings/proxy` | GET/PUT | Configurare proxy de rețea | -| `/api/settings/proxy/test` | POST | Testați conexiunea proxy | -| `/api/settings/ip-filter` | GET/PUT | Lista IP permisă/lista blocată | -| `/api/settings/thinking-budget` | GET/PUT | Bugetul simbol de raționament | -| `/api/settings/system-prompt` | GET/PUT | Sistem global prompt | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Monitorizare +### Monitoring -| Punct final | Metoda | Descriere | -| ------------------------ | ---------- | -------------------------- | -| `/api/sessions` | GET | Urmărire activă a sesiunii | -| `/api/rate-limits` | GET | Limitele ratei per cont | -| `/api/monitoring/health` | GET | Verificarea sănătății | -| `/api/cache` | GET/DELETE | Cache stats / clear | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | ### Backup & Export/Import -| Punct final | Metoda | Descriere | -| --------------------------- | ------ | -------------------------------------------------------- | -| `/api/db-backups` | GET | Listează copiile de rezervă disponibile | -| `/api/db-backups` | PUNE | Creați o copie de rezervă manuală | -| `/api/db-backups` | POST | Restaurare dintr-o anumită copie de rezervă | -| `/api/db-backups/export` | GET | Descărcați baza de date ca fișier .sqlite | -| `/api/db-backups/import` | POST | Încărcați fișierul .sqlite pentru a înlocui baza de date | -| `/api/db-backups/exportAll` | GET | Descărcați backup complet ca arhivă .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | ### Cloud Sync -| Punct final | Metoda | Descriere | -| ---------------------- | ------- | ----------------------------------- | -| `/api/sync/cloud` | Diverse | Operațiuni de sincronizare în cloud | -| `/api/sync/initialize` | POST | Inițializați sincronizarea | -| `/api/cloud/*` | Diverse | Management cloud | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Instrumente CLI +### CLI Tools -| Punct final | Metoda | Descriere | -| ---------------------------------- | ------ | -------------------------- | -| `/api/cli-tools/claude-settings` | GET | Starea Claude CLI | -| `/api/cli-tools/codex-settings` | GET | Status CLI Codex | -| `/api/cli-tools/droid-settings` | GET | Stare CLI Droid | -| `/api/cli-tools/openclaw-settings` | GET | Stare CLI OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | GET | Timp de rulare CLI generic | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Răspunsurile CLI includ: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Reziliență și limite de rată +### ACP Agents -| Punct final | Metoda | Descriere | -| ----------------------- | ------- | ------------------------------------------- | -| `/api/resilience` | GET/PUT | Obține/actualizează profiluri de rezistență | -| `/api/resilience/reset` | POST | Resetați întrerupătoarele | -| `/api/rate-limits` | GET | Starea limitei ratei per cont | -| `/api/rate-limit` | GET | Configurație globală a limitei ratei | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Evaluări +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Punct final | Metoda | Descriere | -| ------------ | -------- | ---------------------------------------------- | -| `/api/evals` | GET/POST | Lista suitelor de evaluare / evaluarea rulării | +### Resilience & Rate Limits -### Politici +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Punct final | Metoda | Descriere | -| --------------- | --------------- | ------------------------------- | -| `/api/policies` | GET/POST/DELETE | Gestionați politicile de rutare | +### Evals -### Conformitate +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Punct final | Metoda | Descriere | -| --------------------------- | ------ | ------------------------------------------- | -| `/api/compliance/audit-log` | GET | Jurnal de audit de conformitate (ultimul N) | +### Policies -### v1beta (compatibil cu Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Punct final | Metoda | Descriere | -| -------------------------- | ------ | ------------------------------------ | -| `/v1beta/models` | GET | Listează modele în format Gemeni | -| `/v1beta/models/{...path}` | POST | Punct final Gemeni `generateContent` | +### Compliance -Aceste puncte finale reflectă formatul API al Gemini pentru clienții care se așteaptă la compatibilitate nativă cu SDK Gemini. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### API-uri interne/de sistem +### v1beta (Gemini-Compatible) -| Punct final | Metoda | Descriere | -| --------------- | ------ | ---------------------------------------------------------------- | -| `/api/init` | GET | Verificarea inițializării aplicației (utilizată la prima rulare) | -| `/api/tags` | GET | Etichete de model compatibile cu Ollama (pentru clienții Ollama) | -| `/api/restart` | POST | Declanșează repornirea grațioasă a serverului | -| `/api/shutdown` | POST | Declanșează închiderea grațioasă a serverului | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Notă:** Aceste puncte finale sunt utilizate intern de sistem sau pentru compatibilitatea clientului Ollama. De obicei, acestea nu sunt apelate de utilizatorii finali. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Transcriere audio +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transcrie fișiere audio folosind Deepgram sau AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Solicitare:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Răspuns:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Furnizori acceptați:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Formate acceptate:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Compatibilitate Ollama +## Ollama Compatibility -Pentru clienții care folosesc formatul API al Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Cererile sunt traduse automat între Ollama și formatele interne. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetrie +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Răspuns:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Buget +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Disponibilitatea modelului +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Procesarea cererii +## Request Processing -1. Clientul trimite cererea către `/v1/*` -2. Apelurile de gestionare a rutei `handleChat`, `handleEmbedding`, `handleAudioTranscription` sau `handleImageGeneration` -3. Modelul este rezolvat (furnizor direct/model sau alias/combo) -4. Acreditări selectate din DB local cu filtrarea disponibilității contului -5. Pentru chat: `handleChatCore` — detectarea formatului, traducerea, verificarea memoriei cache, verificarea idempotității -6. Executorul furnizorului trimite cererea în amonte -7. Răspunsul tradus înapoi în formatul client (chat) sau returnat așa cum este (încorporare/imagini/audio) -8. Utilizare/înregistrare înregistrată -9. Fallback se aplică erorilor conform regulilor combinate +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Referință completă a arhitecturii: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Autentificare +## Authentication -- Rutele tabloului de bord (`/dashboard/*`) folosesc `auth_token` cookie -- Conectarea folosește hash-ul parolei salvate; alternativă la `INITIAL_PASSWORD` -- `requireLogin` comutabil prin `/api/settings/require-login` -- Rutele `/v1/*` necesită opțional cheia API Bearer când `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/ro/ARCHITECTURE.md b/docs/i18n/ro/ARCHITECTURE.md index d87e995079..258d62df53 100644 --- a/docs/i18n/ro/ARCHITECTURE.md +++ b/docs/i18n/ro/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Arhitectura OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Ultima actualizare: 2026-02-18_ +_Last updated: 2026-03-04_ -## Rezumat executiv +## Executive Summary -OmniRoute este un gateway local de rutare AI și un tablou de bord construit pe Next.js. -Acesta oferă un singur punct final compatibil cu OpenAI (`/v1/*`) și direcționează traficul către mai mulți furnizori din amonte cu traducere, alternativă, reîmprospătare token și urmărire a utilizării. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Capacitățile de bază: +Core capabilities: -- Suprafață API compatibilă cu OpenAI pentru CLI/instrumente (28 de furnizori) -- Traducerea cererii/răspunsurilor între formatele furnizorilor -- Alternativ combo de model (secvență cu mai multe modele) -- Rezervă de rezervă la nivel de cont (cu mai multe conturi pentru fiecare furnizor) -- Gestionarea conexiunii furnizorului OAuth + cheie API -- Generare de încorporare prin `/v1/embeddings` (6 furnizori, 9 modele) -- Generare de imagini prin `/v1/images/generations` (4 furnizori, 9 modele) -- Gândiți-vă la analizarea etichetelor (`...`) pentru modele de raționament -- Sanitizarea răspunsului pentru compatibilitate strictă cu OpenAI SDK -- Normalizarea rolurilor (dezvoltator→sistem, sistem→utilizator) pentru compatibilitate între furnizori -- Conversie de ieșire structurată (json_schema → Gemini responseSchema) -- Persistență locală pentru furnizori, chei, aliasuri, combo-uri, setări, prețuri -- Urmărirea utilizării/costurilor și înregistrarea cererilor -- Sincronizare cloud opțională pentru sincronizare multi-dispozitiv/state -- Lista permisă/lista blocată IP pentru controlul accesului API -- Gândire la managementul bugetului (passthrough/auto/personalizat/adaptativ) -- Sistem global de injectare promptă -- Urmărirea sesiunii și amprentarea -- Limitare îmbunătățită a ratei per cont cu profiluri specifice furnizorului -- Model de întrerupător pentru rezistența furnizorului -- Protectie anti-tunet cu blocare mutex -- Cache de deduplicare a cererilor bazate pe semnătură -- Nivelul domeniului: disponibilitatea modelului, regulile de cost, politica de rezervă, politica de blocare -- Persistența stării domeniului (cache-ul de scriere SQLite pentru rezervări, bugete, blocări, întreruptoare de circuit) -- Motor de politici pentru evaluarea centralizată a cererilor (blocare → buget → rezervă) -- Solicitați telemetrie cu agregarea latenței p50/p95/p99 -- ID de corelare (X-Request-Id) pentru urmărirea de la capăt la capăt -- Înregistrare de audit de conformitate cu renunțare pentru fiecare cheie API -- Cadrul de evaluare pentru asigurarea calității LLM -- Tabloul de bord Resilience UI cu starea întreruptorului în timp real -- Furnizori OAuth modulari (12 module individuale sub `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Model de rulare principal: +Primary runtime model: -- Rutele aplicației Next.js sub `src/app/api/*` implementează atât API-uri de tablou de bord, cât și API-uri de compatibilitate -- Un nucleu SSE/rutare partajat în `src/sse/*` + `open-sse/*` se ocupă de execuția furnizorului, traducerea, transmiterea în flux, alternativă și utilizare +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Domeniul de aplicare și limitele +## Scope and Boundaries -### În domeniul de aplicare +### In Scope -- Timp de rulare gateway local -- API-uri de gestionare a tabloului de bord -- Autentificarea furnizorului și reîmprospătarea simbolului -- Solicitați traducere și streaming SSE -- Stare locală + persistență de utilizare -- Orchestrare opțională de sincronizare în cloud +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### În afara domeniului de aplicare +### Out of Scope -- Implementarea serviciului cloud în spatele `NEXT_PUBLIC_CLOUD_URL` -- Furnizor SLA/plan de control în afara procesului local -- Binarele CLI externe în sine (Claude CLI, Codex CLI etc.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Context de sistem la nivel înalt +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Componente Core Runtime +## Core Runtime Components -## 1) API și stratul de rutare (Rute pentru aplicații Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Directoare principale: +Main directories: -- `src/app/api/v1/*` și `src/app/api/v1beta/*` pentru API-uri de compatibilitate -- `src/app/api/*` pentru API-uri de gestionare/configurare -- Următoarea rescrie în harta `next.config.mjs` `/v1/*` în `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Rute importante de compatibilitate: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — include modele personalizate cu `custom: true` -- `src/app/api/v1/embeddings/route.ts` — generare de încorporare (6 furnizori) -- `src/app/api/v1/images/generations/route.ts` — generare de imagini (4+ furnizori inclusiv Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — chat dedicat pentru fiecare furnizor -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — încorporare dedicate pentru fiecare furnizor -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — imagini dedicate pentru fiecare furnizor +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Domenii de management: +Management domains: -- Autentificare/setări: `src/app/api/auth/*`, `src/app/api/settings/*` -- Furnizori/conexiuni: `src/app/api/providers*` -- Noduri furnizor: `src/app/api/provider-nodes*` -- Modele personalizate: `src/app/api/provider-models` (GET/POST/DELETE) -- Catalog de modele: `src/app/api/models/catalog` (GET) -- Configurare proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Chei/alias-uri/combo/preț: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Utilizare: `src/app/api/usage/*` -- Sincronizare/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Ajutor de instrumente CLI: `src/app/api/cli-tools/*` -- Filtru IP: `src/app/api/settings/ip-filter` (GET/PUT) -- Buget de gândire: `src/app/api/settings/thinking-budget` (GET/PUT) -- prompt de sistem: `src/app/api/settings/system-prompt` (GET/PUT) -- Sesiuni: `src/app/api/sessions` (GET) -- Limite de rate: `src/app/api/rate-limits` (GET) -- Reziliență: `src/app/api/resilience` (GET/PATCH) — profiluri furnizor, întrerupător, stare limită a ratei -- Resetare rezistență: `src/app/api/resilience/reset` (POST) — resetare întrerupătoare + cooldowns -- Statistici cache: `src/app/api/cache/stats` (GET/DELETE) -- Disponibilitatea modelului: `src/app/api/models/availability` (GET/POST) -- Telemetrie: `src/app/api/telemetry/summary` (GET) -- Buget: `src/app/api/usage/budget` (GET/POST) -- Lanțuri de rezervă: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Audit de conformitate: `src/app/api/compliance/audit-log` (GET) -- Evaluări: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Politici: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) ## 2) SSE + Translation Core -Module principale de flux: +Main flow modules: -- Intrare: `src/sse/handlers/chat.ts` -- Orchestrare de bază: `open-sse/handlers/chatCore.ts` -- Adaptoare de execuție furnizor: `open-sse/executors/*` -- Format de detectare/configurare furnizor: `open-sse/services/provider.ts` -- Analiza/rezolvarea modelului: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Logica de rezervă a contului: `open-sse/services/accountFallback.ts` -- Registrul traducerilor: `open-sse/translator/index.ts` -- Transformări de flux: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Extragerea/normalizarea utilizării: `open-sse/utils/usageTracking.ts` -- Analizator de etichete de gândire: `open-sse/utils/thinkTagParser.ts` -- Manager de încorporare: `open-sse/handlers/embeddings.ts` -- Încorporarea registrului furnizorului: `open-sse/config/embeddingRegistry.ts` -- Manager de generare a imaginii: `open-sse/handlers/imageGeneration.ts` -- Registrul furnizorului de imagini: `open-sse/config/imageRegistry.ts` -- igienizare răspuns: `open-sse/handlers/responseSanitizer.ts` -- Normalizare rol: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Servicii (logica de afaceri): +Services (business logic): -- Selectarea/punctarea contului: `open-sse/services/accountSelector.ts` -- Gestionarea ciclului de viață a contextului: `open-sse/services/contextManager.ts` -- Aplicarea filtrului IP: `open-sse/services/ipFilter.ts` -- Urmărirea sesiunii: `open-sse/services/sessionManager.ts` -- Solicitați deduplicarea: `open-sse/services/signatureCache.ts` -- Injectarea promptă a sistemului: `open-sse/services/systemPrompt.ts` -- Gândirea bugetului: `open-sse/services/thinkingBudget.ts` -- rutare model wildcard: `open-sse/services/wildcardRouter.ts` -- Gestionarea limitei ratei: `open-sse/services/rateLimitManager.ts` -- Întrerupător: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Module de nivel de domeniu: +Domain layer modules: -- Disponibilitatea modelului: `src/lib/domain/modelAvailability.ts` -- Reguli de cost/bugete: `src/lib/domain/costRules.ts` -- Politica de rezervă: `src/lib/domain/fallbackPolicy.ts` -- Soluție combinată: `src/lib/domain/comboResolver.ts` -- Politica de blocare: `src/lib/domain/lockoutPolicy.ts` -- Motor de politici: `src/domain/policyEngine.ts` — blocare centralizată → buget → evaluare alternativă -- Catalog coduri de eroare: `src/lib/domain/errorCodes.ts` -- ID cerere: `src/lib/domain/requestId.ts` -- Timeout pentru preluare: `src/lib/domain/fetchTimeout.ts` -- Solicitați telemetrie: `src/lib/domain/requestTelemetry.ts` -- Conformitate/audit: `src/lib/domain/compliance/index.ts` -- Runner de evaluare: `src/lib/domain/evalRunner.ts` -- Persistența stării domeniului: `src/lib/db/domainState.ts` — SQLite CRUD pentru lanțuri de rezervă, bugete, istoricul costurilor, starea de blocare, întrerupătoarele de circuit +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Module de furnizor OAuth (12 fișiere individuale sub `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Index de registru: `src/lib/oauth/providers/index.ts` -- Furnizori individuali: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, , , , `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Ambalaj subțire: `src/lib/oauth/providers.ts` — reexporturi din module individuale +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Stratul de persistență +## 3) Persistence Layer -DB de stat primar: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- fișier: `${DATA_DIR}/db.json` (sau `$XDG_CONFIG_HOME/omniroute/db.json` când este setat, altfel `~/.omniroute/db.json`) -- entități: providerConnections, providerNodes, modelAliases, combo-uri, apiKeys, setări, prețuri, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -DB de utilizare: +Usage persistence: -- `src/lib/usageDb.ts` -- fișiere: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- urmează aceeași politică de bază de director ca `localDb` (`DATA_DIR`, apoi `XDG_CONFIG_HOME/omniroute` când este setat) -- descompus în sub-module focalizate: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -DB Stare Domeniu (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — Operații CRUD pentru starea domeniului -- Tabele (create în `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`\_ -- Model de cache de scriere: hărțile din memorie sunt autorizate în timpul execuției; mutațiile sunt scrise sincron cu SQLite; starea este restabilită din DB la pornirea la rece +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Autentificare + Suprafețe de securitate +## 4) Auth + Security Surfaces -- Autentificare cookie pentru tabloul de bord: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Generarea/verificarea cheii API: `src/shared/utils/apiKey.ts` -- Secretele furnizorului au persistat în intrările `providerConnections` -- Suport proxy de ieșire prin `open-sse/utils/proxyFetch.ts` (env vars) și `open-sse/utils/networkProxy.ts` (configurabil per furnizor sau global) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) ## 5) Cloud Sync -- Inițierea planificatorului: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Sarcină periodică: `src/shared/services/cloudSyncScheduler.ts` -- Rută de control: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Ciclul de viață al solicitării (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Flux de rezervă pentru cont +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Deciziile de rezervă sunt conduse de `open-sse/services/accountFallback.ts` folosind coduri de stare și euristică mesaj de eroare. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Ciclul de viață OAuth Onboarding și Token Refresh +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Reîmprospătarea în timpul traficului live este executată în interiorul `open-sse/handlers/chatCore.ts` prin intermediul executorului `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Ciclul de viață Cloud Sync (Activare / Sincronizare / Dezactivare) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Sincronizarea periodică este declanșată de `CloudSyncScheduler` când cloud este activat. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Model de date și hartă de stocare +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Fișiere de stocare fizică: +Physical storage files: -- starea principală: `${DATA_DIR}/db.json` (sau `$XDG_CONFIG_HOME/omniroute/db.json` când este setat, altfel `~/.omniroute/db.json`) -- statistici de utilizare: `${DATA_DIR}/usage.json` -- linii de jurnal de solicitare: `${DATA_DIR}/log.txt` -- sesiuni opționale de traducător/cerere de depanare: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topologie de implementare +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Maparea modulului (decizie critică) +## Module Mapping (Decision-Critical) -### Rută și module API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API-uri de compatibilitate -- `src/app/api/v1/providers/[provider]/*`: rute dedicate pentru fiecare furnizor (chat, încorporare, imagini) -- `src/app/api/providers*`: furnizor CRUD, validare, testare -- `src/app/api/provider-nodes*`: gestionarea nodurilor compatibile personalizate -- `src/app/api/provider-models`: management personalizat model (CRUD) -- `src/app/api/models/catalog`: API de catalog de model complet (toate tipurile grupate după furnizor) -- `src/app/api/oauth/*`: fluxuri OAuth/cod dispozitiv -- `src/app/api/keys*`: ciclul de viață local al cheii API -- `src/app/api/models/alias`: gestionare alias -- `src/app/api/combos*`: gestionarea combo de rezervă -- `src/app/api/pricing`: înlocuirea prețurilor pentru calcularea costurilor -- `src/app/api/settings/proxy`: configurație proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: test de conectivitate proxy de ieșire (POST) -- `src/app/api/usage/*`: API-uri de utilizare și jurnal -- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronizare în cloud și asistență orientată către nor -- `src/app/api/cli-tools/*`: scriitori/verificatori de configurare CLI locale -- `src/app/api/settings/ip-filter`: lista IP permisă/lista blocată (GET/PUT) -- `src/app/api/settings/thinking-budget`: configurația bugetului simbolului de gândire (GET/PUT) -- `src/app/api/settings/system-prompt`: prompt de sistem global (GET/PUT) -- `src/app/api/sessions`: listarea sesiunii active (GET) -- `src/app/api/rate-limits`: starea limită a ratei per cont (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Core de rutare și execuție +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: analizarea cererii, gestionarea combinațiilor, bucla de selecție a contului -- `open-sse/handlers/chatCore.ts`: traducere, expediere executor, reîncercare/reîmprospătare manipulare, configurare flux -- `open-sse/executors/*`: comportamentul de rețea și format specific furnizorului +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Registrul de traduceri și convertoare de format +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: registru și orchestrare a traducătorilor -- Solicitați traducători: `open-sse/translator/request/*` -- Traducători de răspuns: `open-sse/translator/response/*` -- Formatare constante: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Persistență +### Persistence -- `src/lib/localDb.ts`: config/stare persistentă -- `src/lib/usageDb.ts`: istoricul utilizării și jurnalele de solicitare continuă +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Acoperire Executor Furnizor (Model de strategie) +## Provider Executor Coverage (Strategy Pattern) -Fiecare furnizor are un executor specializat care extinde `BaseExecutor` (în `open-sse/executors/base.ts`), care oferă crearea URL, construcția antetului, reîncercarea cu backoff exponențial, cârlige de reîmprospătare a acreditărilor și metoda de orchestrare `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Executant | Furnizor(i) | Manipulare specială | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configurare URL dinamică/antet per furnizor | -| `AntigravityExecutor` | Google Antigravity | ID-uri personalizate de proiect/sesiune, Reîncercați-După analizare | -| `CodexExecutor` | OpenAI Codex | Injectează instrucțiuni de sistem, forțează efortul de raționament | -| `CursorExecutor` | Cursor IDE | Protocolul ConnectRPC, codificarea Protobuf, semnarea cererii prin suma de control | -| `GithubExecutor` | GitHub Copilot | Reîmprospătare jeton Copilot, anteturi care imită VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Format binar AWS EventStream → conversie SSE | -| `GeminiCLIExecutor` | Gemeni CLI | Ciclul de reîmprospătare a simbolului OAuth Google | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Toți ceilalți furnizori (inclusiv noduri compatibile personalizate) folosesc `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matricea de compatibilitate a furnizorilor +## Provider Compatibility Matrix -| Furnizor | Format | Auth | Flux | Non-Stream | Token Refresh | Utilizare API | -| ---------------- | ---------------- | ----------------------------- | ---------------- | ---------- | ------------- | ---------------------- | -| Claude | claude | Cheie API / OAuth | ✅ | ✅ | ✅ | ⚠️ Doar administrator | -| Gemeni | gemeni | Cheie API / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Gemeni CLI | gemeni-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Antigravitație | antigravitație | OAuth | ✅ | ✅ | ✅ | ✅ Cota completă API | -| OpenAI | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-responses | OAuth | ✅ forțat | ❌ | ✅ | ✅ Limite de tarif | -| GitHub Copilot | deschis | OAuth + Token Copilot | ✅ | ✅ | ✅ | ✅ Instantanee de cotă | -| Cursor | cursor | Sumă de control personalizată | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limite de utilizare | -| Qwen | deschis | OAuth | ✅ | ✅ | ✅ | ⚠️ La cerere | -| iFlow | deschis | OAuth (de bază) | ✅ | ✅ | ✅ | ⚠️ La cerere | -| OpenRouter | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | Cheie API | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| Groq | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| Mistral | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| Nedumerire | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| Împreună AI | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| Artificii AI | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| Cerebre | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| Cohere | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Format Acoperire traducere +## Format Translation Coverage -Formatele sursă detectate includ: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Formatele țintă includ: +Target formats include: -- Chat/Răspunsuri OpenAI +- OpenAI chat/Responses - Claude -- Plic Gemeni/Gemeni-CLI/Antigravity +- Gemini/Gemini-CLI/Antigravity envelope - Kiro - Cursor -Traducerile folosesc **OpenAI ca format hub** — toate conversiile trec prin OpenAI ca intermediar: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Traducerile sunt selectate dinamic pe baza formei încărcăturii sursei și a formatului țintă al furnizorului. +Translations are selected dynamically based on source payload shape and provider target format. -Straturi de procesare suplimentare în conducta de traducere: +Additional processing layers in the translation pipeline: -- **Sanitizarea răspunsurilor** — Elimina câmpurile nestandard din răspunsurile în format OpenAI (atât în flux, cât și în non-streaming) pentru a asigura conformitatea strictă cu SDK -- **Normalizarea rolurilor** — Convertește `developer` → `system` pentru ținte non-OpenAI; îmbină `system` → `user` pentru modelele care resping rolul de sistem (GLM, ERNIE) -- **Think tag extraction** — Analizează blocurile `...` din conținut în câmpul `reasoning_content` -- **Ieșire structurată** — Convertește OpenAI `response_format.json_schema` în `responseMimeType` al lui Gemini + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Puncte finale API acceptate +## Supported API Endpoints -| Punct final | Format | Manipulator | -| -------------------------------------------------- | ---------------------- | -------------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Mesaje | Același handler (detectat automat) | -| `POST /v1/responses` | Răspunsuri OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Încorporare OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Lista de modele | Rută API | -| `POST /v1/images/generations` | Imagini OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Lista de modele | Rută API | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicat pentru fiecare furnizor cu validare a modelului | -| `POST /v1/providers/{provider}/embeddings` | Încorporare OpenAI | Dedicat pentru fiecare furnizor cu validare a modelului | -| `POST /v1/providers/{provider}/images/generations` | Imagini OpenAI | Dedicat pentru fiecare furnizor cu validare a modelului | -| `POST /v1/messages/count_tokens` | Claude Token Count | Rută API | -| `GET /v1/models` | Lista de modele OpenAI | Rută API (chat + încorporare + imagine + modele personalizate) | -| `GET /api/models/catalog` | Catalog | Toate modelele grupate după furnizor + tip | -| `POST /v1beta/models/*:streamGenerateContent` | nativ Gemeni | Rută API | -| `GET/PUT/DELETE /api/settings/proxy` | Configurare proxy | Configurare proxy de rețea | -| `POST /api/settings/proxy/test` | Conectivitate proxy | Punct final de testare de sănătate/conectivitate proxy | -| `GET/POST/DELETE /api/provider-models` | Modele personalizate | Gestionare model personalizat per furnizor | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Handler de ocolire +## Bypass Handler -Managerul de ocolire (`open-sse/utils/bypassHandler.ts`) interceptează cererile cunoscute „de aruncat” de la Claude CLI — ping-uri de încălzire, extrageri de titluri și numărătoare de jetonuri — și returnează un **răspuns fals** fără a consuma jetoane de furnizor în amonte. Aceasta este declanșată numai atunci când `User-Agent` conține `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Solicitați Conducta Logger +## Request Logger Pipeline -Loggerul de solicitare (`open-sse/utils/requestLogger.ts`) oferă o conductă de înregistrare a depanării în 7 etape, dezactivată implicit, activată prin `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Fișierele sunt scrise în `/logs//` pentru fiecare sesiune de solicitare. +Files are written to `/logs//` for each request session. -## Moduri de eșec și rezistență +## Failure Modes and Resilience -## 1) Disponibilitatea contului/furnizorului +## 1) Account/Provider Availability -- cooldown contului furnizorului pentru erori tranzitorii/rate/auth -- rezervă de cont înainte de cererea eșuată -- alternativă model combo atunci când modelul curent/calea furnizorului este epuizată +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Expirarea simbolului +## 2) Token Expiry -- preverificare și reîmprospătare cu reîncercare pentru furnizorii care pot fi reîmprospătați -- 401/403 reîncercați după încercarea de reîmprospătare în calea de bază +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Siguranța fluxului +## 3) Stream Safety -- controler de flux conștient de deconectare -- flux de traducere cu spălare la sfârșitul fluxului și gestionarea `[DONE]` -- estimarea utilizării de rezervă atunci când metadatele de utilizare ale furnizorului lipsesc +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Degradarea Cloud Sync +## 4) Cloud Sync Degradation -- apar erori de sincronizare, dar timpul de execuție local continuă -- planificatorul are o logică capabilă să reîncerce, dar execuția periodică apelează în mod implicit sincronizarea cu o singură încercare +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integritatea datelor +## 5) Data Integrity -- Migrare/reparare forme DB pentru cheile lipsă -- garanții de resetare JSON corupte pentru localDb și usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Observabilitate și semnale operaționale +## Observability and Operational Signals -Surse de vizibilitate la runtime: +Runtime visibility sources: -- jurnalele consolei de la `src/sse/utils/logger.ts` -- agregate de utilizare la cerere în `usage.json` -- autentificarea stării cererii textuale `log.txt` -- jurnalele opționale de solicitare profundă/traducere sub `logs/` când `ENABLE_REQUEST_LOGS=true` -- puncte finale de utilizare a tabloului de bord (`/api/usage/*`) pentru consumul UI +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Limite sensibile la securitate +## Security-Sensitive Boundaries -- Secretul JWT (`JWT_SECRET`) securizează verificarea/semnarea cookie-urilor sesiunii de bord -- Parola de rezervă inițială (`INITIAL_PASSWORD`, implicit `123456`) trebuie să fie înlocuită în implementările reale -- Secretul HMAC cheie API (`API_KEY_SECRET`) securizează formatul cheii API locale generate -- Secretele furnizorului (chei/token-uri API) sunt păstrate în DB local și ar trebui protejate la nivel de sistem de fișiere -- Punctele finale de sincronizare în cloud se bazează pe semantica de autentificare a cheii API + ID-ul mașinii +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Mediu și matrice de rulare +## Environment and Runtime Matrix -Variabilele de mediu utilizate în mod activ de cod: +Environment variables actively used by code: -- Aplicație/autentificare: `JWT_SECRET`, `INITIAL_PASSWORD` -- Stocare: `DATA_DIR` -- Comportamentul nodului compatibil: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Suprascriere opțională a bazei de stocare (Linux/macOS când `DATA_DIR` dezactivat): `XDG_CONFIG_HOME` -- Hashing de securitate: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Înregistrare: `ENABLE_REQUEST_LOGS` -- URL sincronizare/cloud: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Proxy de ieșire: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` și variante cu litere mici -- Indicatori de caracteristică SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Ajutor platformă/execuție (configurație nu specifică aplicației): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Note arhitecturale cunoscute +## Known Architectural Notes -1. `usageDb` și `localDb` au acum aceeași politică de bază de director (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) cu migrarea fișierelor moștenite. -2. `/api/v1/route.ts` returnează o listă de modele statice și nu este sursa principală de modele utilizată de `/v1/models`. -3. Loggerul solicitărilor scrie anteturi/corp complet atunci când este activat; tratați directorul de jurnal ca fiind sensibil. -4. Comportamentul în cloud depinde de `NEXT_PUBLIC_BASE_URL` corect și de accesibilitatea punctului final din cloud. -5. Directorul `open-sse/` este publicat ca pachetul `@omniroute/open-sse` **npm workspace**. Codul sursă îl importă prin `@omniroute/open-sse/...` (rezolvat de Next.js `transpilePackages`). Căile fișierelor din acest document folosesc în continuare numele directorului `open-sse/` pentru consecvență. -6. Diagramele din tabloul de bord utilizează **Recharts** (bazate pe SVG) pentru vizualizări analitice accesibile, interactive (diagrame cu bare de utilizare a modelelor, tabele de defalcare a furnizorilor cu rate de succes). -7. Testele E2E folosesc **Playwright** (`tests/e2e/`), rulat prin `npm run test:e2e`. Testele unitare folosesc **Node.js test runner** (`tests/unit/`), rulează prin `npm run test:plan3`. Codul sursă sub `src/` este **TypeScript** (`.ts`/`.tsx`); spațiul de lucru `open-sse/` rămâne JavaScript (`.js`). -8. Pagina Setări este organizată în 5 file: Securitate, Rutare (6 strategii globale: fill-first, round-robin, p2c, aleatoriu, cel mai puțin utilizat, optimizat pentru cost), Reziliență (limite ale ratei editabile, întrerupător de circuit, politici), AI (buget de gândire, prompt de sistem, cache prompt), Avansat (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Lista de verificare a verificării operaționale +## Operational Verification Checklist -- Construire din sursă: `npm run build` -- Creați imaginea Docker: `docker build -t omniroute .` -- Porniți serviciul și verificați: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- Adresa URL de bază țintă CLI ar trebui să fie `http://:20128/v1` când `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ro/CODEBASE_DOCUMENTATION.md b/docs/i18n/ro/CODEBASE_DOCUMENTATION.md index afebb76fbc..303880c198 100644 --- a/docs/i18n/ro/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/ro/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Documentația de bază de cod +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Un ghid cuprinzător, prietenos pentru începători, pentru routerul proxy AI cu mai mulți furnizori **omniroute**. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Ce este omniroute? +## 1. What Is omniroute? -omniroute este un **router proxy** care se află între clienții AI (Claude CLI, Codex, Cursor IDE etc.) și furnizorii AI (Anthropic, Google, OpenAI, AWS, GitHub etc.). Rezolvă o mare problemă: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Diferiți clienți AI vorbesc diferite „limbi” (formate API), iar diferiți furnizori de AI se așteaptă și ei la „limbi” diferite.** Omniroute se traduce automat între ele. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Gândiți-vă la asta ca la un traducător universal la Națiunile Unite - orice delegat poate vorbi orice limbă, iar traducătorul o convertește pentru orice alt delegat. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Privire de ansamblu asupra arhitecturii +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Principiul de bază: Traducerea hub-and-spoke +### Core Principle: Hub-and-Spoke Translation -Toată traducerea formatului trece prin **formatul OpenAI ca hub**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Aceasta înseamnă că aveți nevoie doar de **N traducători** (unul pentru fiecare format) în loc de **N²** (fiecare pereche). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Structura proiectului +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Defalcare modul cu modul +## 4. Module-by-Module Breakdown -### 4.1 Configurare (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**Sursa unică de adevăr** pentru configurația tuturor furnizorilor. +The **single source of truth** for all provider configuration. -| Fișier | Scop | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` obiect cu adrese URL de bază, acreditări OAuth (implicite), anteturi și solicitări implicite de sistem pentru fiecare furnizor. De asemenea, definește `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` și `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Încarcă acreditările externe de la `data/provider-credentials.json` și le îmbină peste valorile implicite codificate în `PROVIDERS`. Păstrează secretele sub controlul sursei, menținând în același timp compatibilitatea cu versiunea inversă. | -| `providerModels.ts` | Registrul central de modele: hărți aliasuri furnizori → ID-uri model. Funcții precum `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Instrucțiuni de sistem injectate în cererile Codex (constrângeri de editare, reguli sandbox, politici de aprobare). | -| `defaultThinkingSignature.ts` | Semnături implicite „de gândire” pentru modelele Claude și Gemini. | -| `ollamaModels.ts` | Definirea schemei pentru modelele locale Ollama (nume, dimensiune, familie, cuantizare). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Flux de încărcare a acreditărilor +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Executori (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Executorii încapsulează **logica specifică furnizorului** utilizând **Modelul de strategie**. Fiecare executant anulează metodele de bază după cum este necesar. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Executant | Furnizor | Specializări cheie | -| ---------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Bază abstractă: crearea adresei URL, anteturi, logica reîncercării, reîmprospătarea acreditărilor | -| `default.ts` | Claude, Gemeni, OpenAI, GLM, Kimi, MiniMax | Reîmprospătare generică a jetonului OAuth pentru furnizorii standard | -| `antigravity.ts` | Cod Google Cloud | Generarea ID-ului de proiect/sesiune, alternativă cu mai multe adrese URL, reîncercare personalizată de analiză din mesajele de eroare („resetare după 2h7m23s”) | -| `cursor.ts` | Cursor IDE | **Cel mai complex**: SHA-256 checksum auth, codificare cerere Protobuf, binar EventStream → analiza răspuns SSE | -| `codex.ts` | OpenAI Codex | Injectează instrucțiuni de sistem, gestionează nivelurile de gândire, elimină parametrii neacceptați | -| `gemini-cli.ts` | Google Gemini CLI | Creare URL personalizată (`streamGenerateContent`), reîmprospătare jeton OAuth Google | -| `github.ts` | GitHub Copilot | Sistem dual token (GitHub OAuth + token Copilot), imitarea antetului VSCode | -| `kiro.ts` | AWS CodeWhisperer | Analiza binară AWS EventStream, cadre de evenimente AMZN, estimare token | -| `index.ts` | — | Fabrică: numele furnizorului de hărți → clasa executorului, cu fallback implicit | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- ### 4.3 Handlers (`open-sse/handlers/`) -**Stratul de orchestrare** — coordonează traducerea, execuția, transmiterea în flux și gestionarea erorilor. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Fișier | Scop | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `chatCore.ts` | **Orchestrator central** (~600 de linii). Se ocupă de ciclul de viață complet al cererii: detectarea formatului → traducerea → expedierea executorului → răspunsul în flux/non-streaming → reîmprospătarea simbolului → gestionarea erorilor → înregistrarea utilizării. | -| `responsesHandler.ts` | Adaptor pentru API-ul OpenAI Responses: convertește formatul de răspunsuri → Terminări de chat → trimite la `chatCore` → convertește SSE înapoi în formatul de răspunsuri. | -| `embeddings.ts` | Managerul de generare de încorporare: rezolvă modelul de încorporare → furnizor, trimite către API-ul furnizorului, returnează un răspuns de încorporare compatibil OpenAI. Suportă peste 6 furnizori. | -| `imageGeneration.ts` | Managerul de generare a imaginii: rezolvă modelul de imagine → furnizor, acceptă modurile compatibile cu OpenAI, Gemini-image (antigravitație) și modurile de rezervă (Nebius). Returnează imagini base64 sau URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Ciclul de viață al cererii (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Servicii (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Logica de afaceri care sprijină manipulatorii și executanții. +Business logic that supports the handlers and executors. -| Fișier | Scop | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Detecție format** (`detectFormat`): analizează structura corpului cererii pentru a identifica formatele Claude/OpenAI/Gemini/Antigravity/Responses (include `max_tokens` euristica pentru Claude). De asemenea: construirea URL, construirea antetului, normalizarea configurației gândirii. Acceptă furnizorii dinamici `openai-compatible-*` și `anthropic-compatible-*`. | -| `model.ts` | Analizarea șirurilor de model (`claude/model-name` → `{provider: "claude", model: "model-name"}`), rezoluția aliasului cu detectarea coliziunilor, dezinfectarea intrării (respinge caracterele de parcurgere/control al căii) și rezoluția informațiilor despre model cu suport pentru obținerea de alias asincron. | -| `accountFallback.ts` | Gestionarea limitelor de rată: retragere exponențială (1s → 2s → 4s → max 2 min), gestionarea timpului de răcire a contului, clasificarea erorilor (care declanșează erorile de rezervă vs. nu). | -| `tokenRefresh.ts` | Actualizare jeton OAuth pentru **fiecare furnizor**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Include memoria cache de deduplicare a promisiunii în timpul zborului și reîncercarea cu backoff exponențial. | -| `combo.ts` | **Modele combinate**: lanțuri de modele de rezervă. Dacă modelul A eșuează cu o eroare eligibilă pentru rezervă, încercați modelul B, apoi C etc. Returnează codurile reale de stare din amonte. | -| `usage.ts` | Preia datele de cotă/utilizare de la API-urile furnizorului (cote GitHub Copilot, cote model antigravitație, limite ale ratei Codex, defalcări de utilizare Kiro, setări Claude). | -| `accountSelector.ts` | Selecția inteligentă a contului cu algoritm de punctare: ia în considerare prioritatea, starea de sănătate, poziția round-robin și starea de cooldown pentru a alege contul optim pentru fiecare solicitare. | -| `contextManager.ts` | Gestionarea ciclului de viață a contextului solicitării: creează și urmărește obiecte de context per-cerere cu metadate (ID-ul cererii, marcaje temporale, informații despre furnizor) pentru depanare și înregistrare. | -| `ipFilter.ts` | Controlul accesului bazat pe IP: acceptă modurile liste de permise și liste de blocare. Validează IP-ul clientului în raport cu regulile configurate înainte de a procesa solicitările API. | -| `sessionManager.ts` | Urmărirea sesiunilor cu amprenta clientului: urmărește sesiunile active folosind identificatori de client hashing, monitorizează numărul de solicitări și oferă valori ale sesiunii. | -| `signatureCache.ts` | Cache de deduplicare bazată pe semnături de solicitare: previne cererile duplicate prin memorarea în cache a semnăturilor de cereri recente și returnarea răspunsurilor memorate în cache pentru cereri identice într-o fereastră de timp. | -| `systemPrompt.ts` | Injectarea globală a promptului de sistem: adaugă sau adaugă un prompt de sistem configurabil la toate solicitările, cu gestionarea compatibilității pentru fiecare furnizor. | -| `thinkingBudget.ts` | Gestionarea bugetului token-ului de raționament: acceptă modurile passthrough, automate (configurație de gândire strip), personalizate (buget fix) și adaptive (scalate la complexitate) pentru controlul simbolurilor de gândire/raționament. | -| `wildcardRouter.ts` | Dirijarea modelului cu caractere wildcard: rezolvă modelele wildcard (de exemplu, `*/claude-*`) în perechi concrete furnizor/model în funcție de disponibilitate și prioritate. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Deduplicare de reîmprospătare a simbolului +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Mașină de stat de rezervă a contului +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Lanț de modele combinate +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Traducător (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**Motorul de traducere a formatului** utilizând un sistem de pluginuri cu auto-înregistrare. +The **format translation engine** using a self-registering plugin system. -#### Arhitectură +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Director | Fișiere | Descriere | -| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 traducători | Convertiți corpurile de solicitare între formate. Fiecare fișier se auto-înregistrează prin `register(from, to, fn)` la import. | -| `response/` | 7 traducători | Conversia fragmentelor de răspuns în flux între formate. Se ocupă de tipurile de evenimente SSE, blocurile de gândire, apelurile de instrumente. | -| `helpers/` | 6 ajutoare | Utilitare partajate: `claudeHelper` (extracția promptului sistemului, configurația gândirii), `geminiHelper` (matarea părților/conținutului), `openaiHelper` (filtrarea formatului), `toolCallHelper` (generarea ID-ului, injectarea răspunsului TOKEN_8 lipsă, \_\_8 NI_EN) `responsesApiHelper`. | -| `index.ts` | — | Motor de traducere: `translateRequest()`, `translateResponse()`, management de stat, registru. | -| `formats.ts` | — | Formatare constante: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, , `CURSOR`, | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Design cheie: pluginuri cu auto-înregistrare +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,17 +395,17 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Utilități (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Fișier | Scop | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Crearea răspunsului la erori (format compatibil cu OpenAI), analizarea erorilor în amonte, extragerea timpului de reîncercare antigravitație din mesajele de eroare, transmiterea erorilor SSE. | -| `stream.ts` | **SSE Transform Stream** — canalul de streaming de bază. Două moduri: `TRANSLATE` (traducere în format complet) și `PASSTHROUGH` (normalizare + extragere utilizare). Se ocupă de stocarea în tampon, estimarea utilizării, urmărirea duratei conținutului. Instanțele de codificator/decodor per-stream evită starea partajată. | -| `streamHelpers.ts` | Utilitare SSE de nivel scăzut: `parseSSELine` (tolerant la spații albe), `hasValuableContent` (filtrează bucăți goale pentru OpenAI/Claude/Gemini), `fixInvalidId`, SSE_103_ware) `perf_metrics` curățare). | -| `usageTracking.ts` | Extragerea utilizării jetoanelor din orice format (Claude/OpenAI/Gemini/Responses), estimare cu rapoarte separate pentru instrumente/mesaj, adăugare de buffer (marja de siguranță de 2000 de jetoane), filtrare câmp specific formatului, înregistrare în consolă cu culori ANSI. | -| `requestLogger.ts` | Înregistrarea cererilor pe bază de fișier (înregistrare prin `ENABLE_REQUEST_LOGS=true`). Creează foldere de sesiune cu fișiere numerotate: `1_req_client.json` → `7_res_client.txt`. Toate I/O sunt asincrone (foc și uitare). Mască anteturile sensibile. | -| `bypassHandler.ts` | Interceptează modele specifice din Claude CLI (extragere titlu, încălzire, numărare) și returnează răspunsuri false fără a apela niciun furnizor. Acceptă atât streaming, cât și non-streaming. Limitat intenționat la domeniul Claude CLI. | -| `networkProxy.ts` | Rezolvă URL-ul proxy de ieșire pentru un anumit furnizor cu prioritate: configurație specifică furnizorului → configurație globală → variabile de mediu (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Acceptă excluderile `NO_PROXY`. Memorează în cache configurația pentru 30 de secunde. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | #### SSE Streaming Pipeline @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Solicitați structura sesiunii de înregistrare +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Stratul de aplicație (`src/`) +### 4.7 Application Layer (`src/`) -| Director | Scop | -| ------------- | --------------------------------------------------------------------------------------- | -| `src/app/` | Interfață de utilizare web, rute API, middleware Express, handlere de apel invers OAuth | -| `src/lib/` | Acces la baza de date (`localDb.ts`, `usageDb.ts`), autentificare, partajat | -| `src/mitm/` | Utilități proxy Man-in-the-middle pentru interceptarea traficului furnizorului | -| `src/models/` | Definițiile modelului bazei de date | -| `src/shared/` | Învelișuri în jurul funcțiilor open-sse (furnizor, flux, eroare etc.) | -| `src/sse/` | Managerii de puncte finale SSE care conectează biblioteca open-sse la rutele Express | -| `src/store/` | Managementul stării aplicației | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Rute API notabile +#### Notable API Routes -| Traseu | Metode | Scop | -| --------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | GET/POST/DELETE | CRUD pentru modele personalizate per furnizor | -| `/api/models/catalog` | GET | Catalog agregat al tuturor modelelor (chat, încorporare, imagine, personalizat) grupate după furnizor | -| `/api/settings/proxy` | GET/PUT/DELETE | Configurație ierarhică de ieșire proxy (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Validează conectivitatea proxy și returnează IP/latența publică | -| `/v1/providers/[provider]/chat/completions` | POST | Finalizări de chat dedicate pentru fiecare furnizor cu validare a modelului | -| `/v1/providers/[provider]/embeddings` | POST | Înglobări dedicate pentru fiecare furnizor cu validare a modelului | -| `/v1/providers/[provider]/images/generations` | POST | Generare de imagini dedicată pentru fiecare furnizor cu validarea modelului | -| `/api/settings/ip-filter` | GET/PUT | Gestionarea listei de permise/liste de blocare IP | -| `/api/settings/thinking-budget` | GET/PUT | Configurarea bugetului simbolului de raționament (passthrough/auto/custom/adaptive) | -| `/api/settings/system-prompt` | GET/PUT | Sistem global de injectare promptă pentru toate solicitările | -| `/api/sessions` | GET | Urmărirea sesiunii active și valorile | -| `/api/rate-limits` | GET | Starea limitei ratei per cont | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Modele de design cheie +## 5. Key Design Patterns -### 5.1 Traducere hub-and-spoke +### 5.1 Hub-and-Spoke Translation -Toate formatele se traduc prin **formatul OpenAI ca hub**. Adăugarea unui furnizor nou necesită doar scrierea **o pereche** de traducători (la/de la OpenAI), nu N perechi. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Modelul Strategiei Executorului +### 5.2 Executor Strategy Pattern -Fiecare furnizor are o clasă de executor dedicată care moștenește de la `BaseExecutor`. Fabrica din `executors/index.ts` îl selectează pe cel potrivit în timpul rulării. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Sistem de pluginuri cu auto-înregistrare +### 5.3 Self-Registering Plugin System -Modulele de traducător se înregistrează la import prin `register()`. Adăugarea unui nou traducător înseamnă doar crearea unui fișier și importarea acestuia. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Retragerea contului cu retragere exponențială +### 5.4 Account Fallback with Exponential Backoff -Atunci când un furnizor returnează 429/401/500, sistemul poate trece la următorul cont, aplicând perioade de răcire exponențiale (1s → 2s → 4s → max 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Lanțuri de modele combinate +### 5.5 Combo Model Chains -Un „combo” grupează mai multe șiruri `provider/model`. Dacă primul eșuează, reveniți automat la următorul. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Traducere în flux cu stat +### 5.6 Stateful Streaming Translation -Traducerea răspunsurilor menține starea în bucățile SSE (urmărirea blocurilor de gândire, acumularea apelurilor de instrumente, indexarea blocurilor de conținut) prin mecanismul `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Utilizare tampon de siguranță +### 5.7 Usage Safety Buffer -Un buffer de 2000 de jetoane este adăugat la utilizarea raportată pentru a preveni clienții să atingă limitele ferestrei de context din cauza supraîncărcării de la solicitările de sistem și traducerea formatului. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Formate acceptate +## 6. Supported Formats -| Format | Direcție | Identificator | -| ------------------------- | ------------- | ------------------ | -| Finalizări de chat OpenAI | sursa + tinta | `openai` | -| OpenAI Responses API | sursa + tinta | `openai-responses` | -| Claude antropic | sursa + tinta | `claude` | -| Google Gemeni | sursa + tinta | `gemini` | -| Google Gemini CLI | doar țintă | `gemini-cli` | -| Antigravitație | sursa + tinta | `antigravity` | -| AWS Kiro | doar țintă | `kiro` | -| Cursor | doar țintă | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Furnizori acceptați +## 7. Supported Providers -| Furnizor | Metoda de autentificare | Executant | Note cheie | -| ------------------------ | ----------------------------- | -------------- | ----------------------------------------------------------------------- | -| Claude antropic | Cheia API sau OAuth | Implicit | Utilizează antetul `x-api-key` | -| Google Gemeni | Cheia API sau OAuth | Implicit | Utilizează antetul `x-goog-api-key` | -| Google Gemini CLI | OAuth | GeminiCLI | Utilizează punctul final `streamGenerateContent` | -| Antigravitație | OAuth | Antigravitație | Alternativ cu mai multe adrese URL, reîncercare personalizată analizare | -| OpenAI | Cheia API | Implicit | Autoritatea purtătorului standard | -| Codex | OAuth | Codex | Injectează instrucțiuni de sistem, gestionează gândirea | -| GitHub Copilot | OAuth + Jeton Copilot | Github | Jeton dublu, imitație antet VSCode | -| Kiro (AWS) | AWS SSO OIDC sau Social | Kiro | Analiza binar EventStream | -| Cursor IDE | Autentificare sumă de control | Cursor | Codificare Protobuf, sume de control SHA-256 | -| Qwen | OAuth | Implicit | Autentificare standard | -| iFlow | OAuth (de bază + purtător) | Implicit | Antet de autentificare dublă | -| OpenRouter | Cheia API | Implicit | Autoritatea purtătorului standard | -| GLM, Kimi, MiniMax | Cheia API | Implicit | Compatibil cu Claude, utilizați `x-api-key` | -| `openai-compatible-*` | Cheia API | Implicit | Dinamic: orice punct final compatibil OpenAI | -| `anthropic-compatible-*` | Cheia API | Implicit | Dinamic: orice punct final compatibil cu Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Rezumatul fluxului de date +## 8. Data Flow Summary -### Solicitare de streaming +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Solicitare non-streaming +### Non-Streaming Request ```mermaid flowchart LR diff --git a/docs/i18n/ro/FEATURES.md b/docs/i18n/ro/FEATURES.md index abd4b2b5fc..82cc73b67b 100644 --- a/docs/i18n/ro/FEATURES.md +++ b/docs/i18n/ro/FEATURES.md @@ -1,22 +1,22 @@ -# OmniRoute — Galeria de funcții din tabloul de bord +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Ghid vizual pentru fiecare secțiune a tabloului de bord OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Furnizori +## 🔌 Providers -Gestionați conexiunile furnizorilor AI: furnizori OAuth (Claude Code, Codex, Gemini CLI), furnizori de chei API (Groq, DeepSeek, OpenRouter) și furnizori gratuiti (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Combo +## 🎨 Combos -Creați combinații de modele de rutare cu 6 strategii: umplere mai întâi, round-robin, putere a două alegeri, aleatoriu, cel mai puțin utilizat și optimizat din punct de vedere al costurilor. Fiecare combo înlănțuiește mai multe modele cu fallback automat. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) @@ -24,47 +24,83 @@ Creați combinații de modele de rutare cu 6 strategii: umplere mai întâi, rou ## 📊 Analytics -Analiză cuprinzătoare a utilizării cu consum de simboluri, estimări de costuri, hărți termice ale activității, diagrame de distribuție săptămânală și defalcări pentru fiecare furnizor. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Sănătatea sistemului +## 🏥 System Health -Monitorizare în timp real: timp de funcționare, memorie, versiune, percentile de latență (p50/p95/p99), statistici cache și stări întrerupătoarelor furnizorului. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Loc de joacă pentru traducător +## 🔧 Translator Playground -Patru moduri de depanare a traducerilor API: **Playground** (convertor de format), **Chat Tester** (cereri live), **Test Bench** (testare în lot) și **Live Monitor** (stream în timp real). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Setări +## 🎮 Model Playground _(v2.0.9+)_ -Setări generale, stocare de sistem, management de backup (bază de date de export/import), aspect (mod întunecat/luminos), securitate (include protecția punctelor terminale API și blocarea furnizorilor personalizați), rutare, reziliență și configurație avansată. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Instrumente CLI +## 🔧 CLI Tools -Configurare cu un singur clic pentru instrumentele de codare AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code și Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Solicitați jurnalele +## 🤖 CLI Agents _(v2.0.11+)_ -Înregistrare în timp real a cererilor cu filtrare în funcție de furnizor, model, cont și cheie API. Afișează codurile de stare, utilizarea simbolurilor, latența și detaliile răspunsului. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) @@ -72,6 +108,35 @@ Configurare cu un singur clic pentru instrumentele de codare AI: Claude Code, Co ## 🌐 API Endpoint -Punctul final API unificat cu defalcarea capacităților: Terminări de chat, încorporare, Generare de imagini, Reclasificare, Transcriere audio și chei API înregistrate. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ro/TROUBLESHOOTING.md b/docs/i18n/ro/TROUBLESHOOTING.md index d303e9f896..120092d63c 100644 --- a/docs/i18n/ro/TROUBLESHOOTING.md +++ b/docs/i18n/ro/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Depanare +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Probleme și soluții comune pentru OmniRoute. +Common problems and solutions for OmniRoute. --- -## Remedieri rapide +## Quick Fixes -| Problemă | Soluție | -| -------------------------------------------- | ----------------------------------------------------------------------------- | -| Prima conectare nu funcționează | Verificați `INITIAL_PASSWORD` în `.env` (implicit: `123456`) | -| Tabloul de bord se deschide pe portul greșit | Setați `PORT=20128` și `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Niciun jurnal de solicitare sub `logs/` | Setați `ENABLE_REQUEST_LOGS=true` | -| EACCES: permisiunea refuzată | Setați `DATA_DIR=/path/to/writable/dir` să înlocuiască `~/.omniroute` | -| Strategia de rutare nu se salvează | Actualizare la v1.4.11+ (remedierea schemei Zod pentru persistența setărilor) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Probleme cu furnizorii +## Provider Issues -### „Modelul de limbă nu a furnizat mesaje” +### "Language model did not provide messages" -**Cauza:** Cota de furnizor epuizată. +**Cause:** Provider quota exhausted. -**Remediere:** +**Fix:** -1. Verificați instrumentul de urmărire a cotelor din tabloul de bord -2. Utilizați un combo cu niveluri de rezervă -3. Treceți la nivelul mai ieftin/gratuit +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Limitarea ratei +### Rate Limiting -**Cauza:** Cota de abonament epuizată. +**Cause:** Subscription quota exhausted. -**Remediere:** +**Fix:** -- Adăugați alternativă: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Utilizați GLM/MiniMax ca rezervă ieftină +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Token OAuth a expirat +### OAuth Token Expired -OmniRoute reîmprospătează automat jetoanele. Dacă problemele persistă: +OmniRoute auto-refreshes tokens. If issues persist: -1. Tabloul de bord → Furnizor → Reconectare -2. Ștergeți și adăugați din nou conexiunea la furnizor +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Probleme cu cloudul +## Cloud Issues -### Erori de sincronizare în cloud +### Cloud Sync Errors -1. Verificați `BASE_URL` puncte către instanța dvs. care rulează (de exemplu, `http://localhost:20128`) -2. Verificați `CLOUD_URL` puncte către punctul final de cloud (de exemplu, `https://omniroute.dev`) -3. Păstrați valorile `NEXT_PUBLIC_*` aliniate cu valorile de pe server +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Returnează 500 +### Cloud `stream=false` Returns 500 -**Simptom:** `Unexpected token 'd'...` pe punctul final cloud pentru apeluri care nu sunt transmise în flux. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Cauza:** Upstream returnează sarcina utilă SSE în timp ce clientul așteaptă JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Soluție:** utilizați `stream=true` pentru apelurile directe în cloud. Timpul de rulare local include SSE→JSON fallback. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud spune Conectat, dar „Cheie API nevalidă” +### Cloud Says Connected but "Invalid API key" -1. Creați o cheie nouă din tabloul de bord local (`/api/keys`) -2. Rulați sincronizarea în cloud: Activați Cloud → Sincronizare acum -3. Cheile vechi/nesincronizate pot reveni în continuare `401` pe cloud +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Probleme cu Docker +## Docker Issues -### Instrumentul CLI arată că nu este instalat +### CLI Tool Shows Not Installed -1. Verificați câmpurile de rulare: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Pentru modul portabil: utilizați imaginea țintă `runner-cli` (CLI-uri incluse) -3. Pentru modul de montare gazdă: setați `CLI_EXTRA_PATHS` și montați directorul bin gazdă ca doar citire -4. Dacă `installed=true` și `runnable=false`: binarul a fost găsit, dar verificarea de sănătate a eșuat +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Validare rapidă de rulare +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Probleme de cost +## Cost Issues -### Costuri ridicate +### High Costs -1. Verificați statisticile de utilizare în Tabloul de bord → Utilizare -2. Comutați modelul principal la GLM/MiniMax -3. Utilizați nivelul gratuit (Gemini CLI, iFlow) pentru sarcini necritice -4. Setați bugete de cost pentru fiecare cheie API: Tabloul de bord → Chei API → Buget +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Depanare +## Debugging -### Activați jurnalele de solicitări +### Enable Request Logs -Setați `ENABLE_REQUEST_LOGS=true` în fișierul dvs. `.env`. Jurnalele apar în directorul `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Verificați sănătatea furnizorului +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Spațiu de rulare +### Runtime Storage -- Stare principală: `${DATA_DIR}/db.json` (furnizori, combo-uri, aliasuri, chei, setări) -- Utilizare: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Jurnalele de solicitare: `/logs/...` (când `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Probleme cu întrerupătorul de circuit +## Circuit Breaker Issues -### Furnizor blocat în stare DESCHIS +### Provider stuck in OPEN state -Când întrerupătorul unui furnizor este DESCHIS, cererile sunt blocate până la expirarea perioadei de răcire. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Remediere:** +**Fix:** -1. Accesați **Tabloul de bord → Setări → Reziliență** -2. Verificați cardul întreruptorului pentru furnizorul afectat -3. Faceți clic pe **Reset All** pentru a șterge toate întrerupătoarele sau așteptați ca perioada de răcire să expire -4. Verificați că furnizorul este efectiv disponibil înainte de resetare +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Furnizorul continuă să declanșeze întrerupătorul +### Provider keeps tripping the circuit breaker -Dacă un furnizor intră în mod repetat în starea DESCHIS: +If a provider repeatedly enters OPEN state: -1. Verificați **Tabloul de bord → Sănătate → Sănătatea furnizorului** pentru modelul de eșec -2. Accesați **Setări → Reziliență → Profiluri furnizor** și creșteți pragul de eșec -3. Verificați dacă furnizorul a modificat limitele API sau dacă necesită re-autentificare -4. Examinați telemetria latenței — latența mare poate cauza eșecuri bazate pe timeout +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Probleme cu transcrierea audio +## Audio Transcription Issues -### Eroare „Model neacceptat”. +### "Unsupported model" error -- Asigurați-vă că utilizați prefixul corect: `deepgram/nova-3` sau `assemblyai/best` -- Verificați că furnizorul este conectat în **Tabloul de bord → Furnizori** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Transcrierea revine goală sau eșuează +### Transcription returns empty or fails -- Verificați formatele audio acceptate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Verificați că dimensiunea fișierului este în limitele furnizorului (de obicei < 25 MB) -- Verificați valabilitatea cheii API a furnizorului în cardul furnizorului +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Depanare a traducătorului +## Translator Debugging -Utilizați **Tabloul de bord → Traducător** pentru a depana problemele de traducere de format: +Use **Dashboard → Translator** to debug format translation issues: -| Modul | Când să utilizați | -| ------------------- | ----------------------------------------------------------------------------------------------------------------- | -| **Teren de joacă** | Comparați formatele de intrare/ieșire una lângă alta — inserați o solicitare eșuată pentru a vedea cum se traduce | -| **Tester de chat** | Trimiteți mesaje live și inspectați întreaga sarcină de solicitare/răspuns, inclusiv antetele | -| **Banc de testare** | Rulați teste în loturi în combinații de formate pentru a afla ce traduceri sunt întrerupte | -| **Monitor live** | Urmăriți fluxul de solicitări în timp real pentru a detecta problemele intermitente de traducere | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Probleme frecvente de format +### Common format issues -- **Nu apar etichete de gândire** — Verificați dacă furnizorul țintă acceptă gândirea și setarea bugetului de gândire -- **Scăderea apelurilor de instrumente** — Unele traduceri în format pot elimina câmpurile neacceptate; verificați în modul Playground -- **Lipsește promptul de sistem** — Claude și Gemini gestionează prompturile în mod diferit; verificați rezultatul traducerii -- **SDK returnează șir brut în loc de obiect** — Remediat în v1.1.0: dezinfectantul de răspuns acum elimină câmpurile nestandard (`x_groq`, `usage_breakdown` etc.) care cauzează eșecuri de validare OpenAI SDK Pydantic -- **GLM/ERNIE respinge rolul `system`** — Remediat în v1.1.0: normalizatorul de roluri îmbină automat mesajele de sistem în mesajele utilizatorului pentru modele incompatibile -- **`developer` rol nerecunoscut** — Remediat în v1.1.0: convertit automat în `system` pentru furnizorii non-OpenAI -- **`json_schema` nu funcționează cu Gemini** — Remediat în v1.1.0: `response_format` este acum convertit în `responseMimeType` + `responseSchema` al lui Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Setări de rezistență +## Resilience Settings -### Limita automată a ratei nu se declanșează +### Auto rate-limit not triggering -- Limita automată a ratei se aplică numai furnizorilor de chei API (nu OAuth/abonament) -- Verificați că **Setări → Reziliență → Profiluri furnizorului** are limita de rata automată activată -- Verificați dacă furnizorul returnează codurile de stare `429` sau anteturile `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Reglarea retragerii exponențiale +### Tuning exponential backoff -Profilurile furnizorilor acceptă aceste setări: +Provider profiles support these settings: -- **Întârziere de bază** — Timp de așteptare inițial după prima defecțiune (implicit: 1s) -- **Întârziere maximă** — Limită maximă a timpului de așteptare (implicit: 30s) -- **Multiplicator** — Cât de mult se mărește întârzierea pentru fiecare defecțiune consecutivă (implicit: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Turma anti-tunet +### Anti-thundering herd -Când multe solicitări concurente ajung la un furnizor cu o rată limitată, OmniRoute folosește mutex + limitarea automată a ratei pentru a serializa cererile și a preveni eșecurile în cascadă. Acest lucru este automat pentru furnizorii de chei API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Încă blocat? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Probleme GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arhitectură**: Consultați [link](ARCHITECTURE.md) pentru detalii interne -- **Referință API**: Consultați [link](API_REFERENCE.md) pentru toate punctele finale -- **Tabloul de bord pentru sănătate**: verificați **Tabloul de bord → Sănătate** pentru starea sistemului în timp real -- **Translator**: utilizați **Tabloul de bord → Translator** pentru a depana problemele de format +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/ro/USER_GUIDE.md b/docs/i18n/ro/USER_GUIDE.md index 5027ce4e6f..5a043224df 100644 --- a/docs/i18n/ro/USER_GUIDE.md +++ b/docs/i18n/ro/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Ghidul utilizatorului +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Ghid complet pentru configurarea furnizorilor, crearea combo-urilor, integrarea instrumentelor CLI și implementarea OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Cuprins +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Ghid complet pentru configurarea furnizorilor, crearea combo-urilor, integrarea --- -## 💰 Prețurile dintr-o privire +## 💰 Pricing at a Glance -| Nivelul | Furnizor | Cost | Resetare cotă | Cel mai bun pentru | -| ---------------- | ----------------- | ------------------ | --------------------------- | ------------------------- | -| **💳 ABONARE** | Claude Code (Pro) | 20 USD/lună | 5h + săptămânal | Deja abonat | -| | Codex (Plus/Pro) | 20-200 USD/lună | 5h + săptămânal | Utilizatori OpenAI | -| | Gemeni CLI | **GRATIS** | 180K/lună + 1K/zi | Toată lumea! | -| | GitHub Copilot | 10-19 USD/lună | Lunar | utilizatorii GitHub | -| **🔑 CHEIA API** | DeepSeek | Plată pe utilizare | Niciuna | Raționament ieftin | -| | Groq | Plată pe utilizare | Niciuna | Inferență ultra-rapidă | -| | xAI (Grok) | Plată pe utilizare | Niciuna | Grok 4 raționament | -| | Mistral | Plată pe utilizare | Niciuna | Modele găzduite de UE | -| | Nedumerire | Plată pe utilizare | Niciuna | Căutare sporită | -| | Împreună AI | Plată pe utilizare | Niciuna | Modele open-source | -| | Artificii AI | Plată pe utilizare | Niciuna | Imagini Fast FLUX | -| | Cerebre | Plată pe utilizare | Niciuna | Viteza la scara plachetei | -| | Cohere | Plată pe utilizare | Niciuna | Comanda R+ RAG | -| | NVIDIA NIM | Plată pe utilizare | Niciuna | Modele de întreprindere | -| **💰 IEFTIN** | GLM-4.7 | 0,6 USD/1 milion | Zilnic 10:00 | Backup buget | -| | MiniMax M2.1 | 0,2 USD/1 milion | rulare de 5 ore | Cea mai ieftină opțiune | -| | Kimi K2 | 9 USD/lună plat | 10 milioane de jetoane/lună | Cost previzibil | -| **🆓 GRATUIT** | iFlow | $0 | Nelimitat | 8 modele gratuite | -| | Qwen | $0 | Nelimitat | 3 modele gratuite | -| | Kiro | $0 | Nelimitat | Claude liber | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Sfat profesionist:** Începeți cu Gemini CLI (180K gratuit/lună) + iFlow (gratuit nelimitat) combo = cost 0 USD! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Cazuri de utilizare +## 🎯 Use Cases -### Cazul 1: „Am abonament Claude Pro” +### Case 1: "I have Claude Pro subscription" -**Problemă:** Cota expiră neutilizată, limitele ratei în timpul codării grele +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Cazul 2: „Vreau cost zero” +### Case 2: "I want zero cost" -**Problemă:** Nu-mi permit abonamente, au nevoie de codare AI de încredere +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Cazul 3: „Am nevoie de codare 24/7, fără întreruperi” +### Case 3: "I need 24/7 coding, no interruptions" -**Problemă:** Termenele limită, nu-mi permit timpi de nefuncționare +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Cazul 4: „Vreau AI GRATUIT în OpenClaw” +### Case 4: "I want FREE AI in OpenClaw" -**Problemă:** Aveți nevoie de asistent AI în aplicațiile de mesagerie, complet gratuit +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Configurarea furnizorului +## 📖 Provider Setup -### 🔐 Furnizori de abonament +### 🔐 Subscription Providers -#### Cod Claude (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Sfat profesionist:** Folosiți Opus pentru sarcini complexe, Sonnet pentru viteză. OmniRoute urmărește cota per model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (GRATIS 180K/lună!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,7 +152,7 @@ Models: gc/gemini-2.5-pro ``` -**Cea mai bună valoare:** Nivel gratuit imens! Utilizați acest lucru înainte de nivelurile plătite. +**Best Value:** Huge free tier! Use this before paid tiers. #### GitHub Copilot @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Furnizori ieftini +### 💰 Cheap Providers -#### GLM-4.7 (Resetare zilnică, 0,6 USD/1 milion) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Înscrieți-vă: [Zhipu AI](https://open.bigmodel.cn/) -2. Obțineți cheia API din Coding Plan -3. Tabloul de bord → Adăugați cheie API: Furnizor: `glm`, Cheie API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Utilizați:** `glm/glm-4.7` — **Sfat profesionist:** Planul de codare oferă cotă de 3 ori la 1/7 cost! Resetați zilnic la 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (resetare în 5 ore, 0,20 USD/1 milion) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Înscrieți-vă: [MiniMax](https://www.minimax.io/) -2. Obțineți cheia API → Tabloul de bord → Adăugați cheia API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Utilizați:** `minimax/MiniMax-M2.1` — **Sfat profesionist:** Cea mai ieftină opțiune pentru context lung (1 milion de jetoane)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (9 USD/lună fix) +#### Kimi K2 ($9/month flat) -1. Abonați-vă: [Moonshot AI](https://platform.moonshot.ai/) -2. Obțineți cheia API → Tabloul de bord → Adăugați cheia API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Utilizați:** `kimi/kimi-latest` — **Sfat pro:** Fix 9 USD/lună pentru 10 milioane de jetoane = 0,90 USD/1 milion cost efectiv! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 Furnizori GRATUITI +### 🆓 FREE Providers -#### iFlow (8 modele GRATUITE) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 modele GRATUITE) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude GRATUIT) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Combo +## 🎨 Combos -### Exemplul 1: Maximizați abonamentul → Backup ieftin +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Exemplul 2: Numai gratuit (cost zero) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,7 +249,7 @@ Cost: $0 forever! --- -## 🔧 Integrare CLI +## 🔧 CLI Integration ### Cursor IDE @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Claude Cod +### Claude Code -Editați `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Editați `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Editați `~/.openclaw/openclaw.json`: } ``` -**Sau utilizați Dashboard:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Continuare / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Desfășurare +## 🚀 Deployment -### Implementare VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Pentru modul integrat în gazdă cu binare CLI, consultați secțiunea Docker din documentele principale. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Variabile de mediu +### Environment Variables -| Variabila | Implicit | Descriere | -| --------------------- | ------------------------------------ | -------------------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Secret de semnare JWT (**schimbarea producției**) | -| `INITIAL_PASSWORD` | `123456` | Prima parolă de conectare | -| `DATA_DIR` | `~/.omniroute` | Director de date (db, utilizare, jurnale) | -| `PORT` | cadru implicit | Port de serviciu (`20128` în exemple) | -| `HOSTNAME` | cadru implicit | Leagă gazdă (Docker este implicit la `0.0.0.0`) | -| `NODE_ENV` | implicit de rulare | Setați `production` pentru implementare | -| `BASE_URL` | `http://localhost:20128` | Adresa URL de bază internă pe partea serverului | -| `CLOUD_URL` | `https://omniroute.dev` | Adresa URL de bază a punctului final de sincronizare în cloud | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Secret HMAC pentru cheile API generate | -| `REQUIRE_API_KEY` | `false` | Aplicați cheia API Bearer pe `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Activează jurnalele cereri/răspuns | -| `AUTH_COOKIE_SECURE` | `false` | Forțați cookie-ul de autentificare `Secure` (în spatele proxy-ului invers HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Pentru referința completă a variabilei de mediu, consultați [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Modele disponibile +## 📊 Available Models
-Vedeți toate modelele disponibile +View all available models -**Cod Claude (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**CLI Gemini (`gc/`)** — GRATUIT: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Copilot GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — 0,6 USD/1 milion: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — 0,2 USD/1 milion: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATUIT: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATUIT: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATUIT: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,13 +460,13 @@ Pentru referința completă a variabilei de mediu, consultați [README](../READM **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Perplexitate (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` **Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Focuri de artificii AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Cerebre (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` **Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` @@ -417,11 +476,11 @@ Pentru referința completă a variabilei de mediu, consultați [README](../READM --- -## 🧩 Funcții avansate +## 🧩 Advanced Features -### Modele personalizate +### Custom Models -Adăugați orice ID de model oricărui furnizor fără a aștepta o actualizare a aplicației: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Sau utilizați Tabloul de bord: **Furnizori → [Furnizor] → Modele personalizate**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Rute de furnizori dedicate +### Dedicated Provider Routes -Dirijați cererile direct către un anumit furnizor cu validarea modelului: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Prefixul furnizorului este adăugat automat dacă lipsește. Modelele nepotrivite revin `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Configurare proxy de rețea +### Network Proxy Configuration ```bash # Set global proxy @@ -463,7 +522,7 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Precedență:** Specific cheie → Specific combo → Specific furnizor → Global → Mediu. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. ### Model Catalog API @@ -471,68 +530,68 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ curl http://localhost:20128/api/models/catalog ``` -Returnează modele grupate după furnizor cu tipuri (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). ### Cloud Sync -- Sincronizați furnizorii, combo-urile și setările pe dispozitive -- Sincronizare automată în fundal cu timeout + fail-rapid -- Prefer partea serverului `BASE_URL`/`CLOUD_URL` în producție +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (Faza 9) +### LLM Gateway Intelligence (Phase 9) -- **Cache semantic** — Memorează automat în cache non-streaming, temperatură=0 răspunsuri (ocolire cu `X-OmniRoute-No-Cache: true`) -- **Solicitare Idempotency** — Deduplică cererile în 5s prin antetul sau `X-Request-Id` -- **Urmărirea progresului** — Opt-in SSE `event: progress` evenimente prin antetul `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- ### Translator Playground -Acces prin **Tabloul de bord → Translator**. Depanați și vizualizați modul în care OmniRoute traduce cererile API între furnizori. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Modul | Scop | -| ------------------- | ----------------------------------------------------------------------------------------------------- | -| **Teren de joacă** | Selectați formatele sursă/țintă, inserați o solicitare și vedeți instantaneu rezultatul tradus | -| **Tester de chat** | Trimiteți mesaje de chat live prin proxy și inspectați întregul ciclu de solicitare/răspuns | -| **Banc de testare** | Rulați teste în loturi în mai multe combinații de formate pentru a verifica corectitudinea traducerii | -| **Monitor live** | Urmăriți traducerile în timp real pe măsură ce solicitările curg prin proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Cazuri de utilizare:** +**Use cases:** -- Depanați de ce o anumită combinație client/furnizor eșuează -- Verificați dacă etichetele de gândire, apelurile de instrumente și instrucțiunile de sistem se traduc corect -- Comparați diferențele de format dintre formatele OpenAI, Claude, Gemini și Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Strategii de rutare +### Routing Strategies -Configurați prin **Tablou de bord → Setări → Rutare**. +Configure via **Dashboard → Settings → Routing**. -| Strategie | Descriere | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| **Umpleți mai întâi** | Utilizează conturile în ordine de prioritate — contul principal gestionează toate solicitările până când nu sunt disponibile | -| **Round Robin** | Parcurge toate conturile cu o limită stabilă configurabilă (implicit: 3 apeluri per cont) | -| **P2C (Puterea a două opțiuni)** | Alege 2 conturi aleatorii și rute către cel mai sănătos — echilibrează sarcina cu conștientizarea sănătății | -| **La întâmplare** | Selectează aleatoriu un cont pentru fiecare solicitare folosind Fisher-Yates shuffle | -| **Cel mai puțin folosit** | Rute către contul cu cea mai veche amprentă temporală `lastUsedAt`, distribuind traficul uniform | -| **Cost optimizat** | Rute către contul cu cea mai mică valoare de prioritate, optimizare pentru furnizorii cu cel mai mic cost | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Aliasuri de model cu caractere wildcard +#### Wildcard Model Aliases -Creați modele de metacară pentru a remapa numele modelelor: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Wildcard-urile acceptă `*` (orice caractere) și `?` (un singur caracter). +Wildcards support `*` (any characters) and `?` (single character). -#### Lanțuri de rezervă +#### Fallback Chains -Definiți lanțuri globale de rezervă care se aplică tuturor solicitărilor: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Reziliență și întrerupătoare de circuit +### Resilience & Circuit Breakers -Configurați prin **Tabloul de bord → Setări → Reziliență**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementează rezistența la nivel de furnizor cu patru componente: +OmniRoute implements provider-level resilience with four components: -1. **Profiluri de furnizor** — Configurație per furnizor pentru: - - Pragul de eșec (cate defecțiuni înainte de deschidere) - - Durata de răcire - - Sensibilitatea de detectare a limitei ratei - - Parametrii de backoff exponenţial +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Limite de rată editabile** — Setări implicite la nivel de sistem configurabile în tabloul de bord: - - **Solicitări pe minut (RPM)** — Numărul maxim de solicitări pe minut per cont - - **Timp minim între solicitări** — Intervalul minim în milisecunde între solicitări - - **Max. de solicitări simultane** — Maxim de solicitări simultane per cont - - Faceți clic pe **Editați** pentru a modifica, apoi pe **Salvați** sau **Anulați**. Valorile persistă prin intermediul API-ului de rezistență. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** — Urmărește defecțiunile pentru fiecare furnizor și deschide automat circuitul când este atins un prag: - - **ÎNCHIS** (sănătos) — Solicitările curg normal - - **DESCHIS** — Furnizorul este blocat temporar după eșecuri repetate - - **HALF_OPEN** — Se testează dacă furnizorul și-a revenit +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Politici și identificatori blocați** — Afișează starea întrerupătorului și identificatorii blocați cu capacitatea de deblocare forțată. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Detecție automată a limitei ratei** — Monitorizează anteturile `429` și `Retry-After` pentru a evita în mod proactiv atingerea limitelor ratei furnizorului. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Sfat profesionist:** Folosiți butonul **Reset All** pentru a șterge toate întreruptoarele de circuit și perioadele de răcire atunci când un furnizor își revine după o întrerupere. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Export/Import baze de date +### Database Export / Import -Gestionați copiile de rezervă ale bazei de date în **Tabloul de bord → Setări → Sistem și stocare**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Acțiune | Descriere | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Exportați baza de date** | Descarcă baza de date SQLite curentă ca fișier `.sqlite` | -| **Exportați toate (.tar.gz)** | Descărcă o arhivă de rezervă completă, inclusiv: bază de date, setări, combinații, conexiuni la furnizor (fără acreditări), metadatele cheii API | -| **Importă baza de date** | Încărcați un fișier `.sqlite` pentru a înlocui baza de date curentă. O copie de rezervă pre-import este creată automat | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Validare import:** Fișierul importat este validat pentru integritate (verificare pragma SQLite), tabelele necesare (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) și dimensiune (max. 100 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Cazuri de utilizare:** +**Use Cases:** -- Migrați OmniRoute între mașini -- Creați copii de rezervă externe pentru recuperarea în caz de dezastru -- Partajați configurațiile între membrii echipei (exportați toate → partajați arhiva) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Tabloul de bord pentru setări +### Settings Dashboard -Pagina de setări este organizată în 5 file pentru o navigare ușoară: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Cuprins | -| -------------- | ----------------------------------------------------------------------------------------------------------------------- | -| **Securitate** | Setări de conectare/parolă, control acces IP, autentificare API pentru `/models` și blocare furnizor | -| **Dirutare** | Strategie globală de rutare (6 opțiuni), aliasuri de model cu wildcard, lanțuri de rezervă, valori implicite combo | -| **Reziliență** | Profilurile furnizorilor, limitele de rată modificabile, starea întrerupătorului, politicile și identificatorii blocați | -| **AI** | Gândire la configurația bugetului, injectarea promptă a sistemului global, statisticile cache prompte | -| **Avansat** | Configurație globală proxy (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Costuri și management bugetar +### Costs & Budget Management -Acces prin **Tabloul de bord → Costuri**. +Access via **Dashboard → Costs**. -| Tab | Scop | -| ----------- | ------------------------------------------------------------------------------------------------------------------ | -| **Buget** | Setați limite de cheltuieli pentru fiecare cheie API cu bugete zilnice/săptămânale/lunare și urmărire în timp real | -| **Prețuri** | Vizualizați și editați intrările de prețuri ale modelului — cost pe 1K jetonuri de intrare/ieșire per furnizor | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Urmărirea costurilor:** Fiecare solicitare înregistrează utilizarea simbolurilor și calculează costul utilizând tabelul de prețuri. Vedeți defalcări în **Tabloul de bord → Utilizare** în funcție de furnizor, model și cheie API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Transcriere audio +### Audio Transcription -OmniRoute acceptă transcrierea audio prin punctul final compatibil cu OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Furnizori disponibili: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Formate audio acceptate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Strategii de echilibrare combinate +### Combo Balancing Strategies -Configurați echilibrarea per-combo în **Tabloul de bord → Combo → Creare/Editare → Strategie**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategie | Descriere | -| ----------------------------------------------- | ------------------------------------------------------------------------------------- | -| **Round-Robin** | Se rotește succesiv prin modele | -| **Prioritate** | Încearcă întotdeauna primul model; cade înapoi numai pe eroare | -| **La întâmplare** | Alege un model aleatoriu din combo pentru fiecare cerere | -| **Ponderat** | Rute proporționale pe baza greutăților atribuite per model | -| **Cel mai puțin folosit** | Rute către modelul cu cele mai puține solicitări recente (folosește valori combinate) | -| **Optimizat din punct de vedere al costurilor** | Rute către cel mai ieftin model disponibil (folosește tabelul de prețuri) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Valorile implicite globale ale combo pot fi setate în **Tabloul de bord → Setări → Rutare → Setări implicite combo**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Tabloul de bord pentru sănătate +### Health Dashboard -Acces prin **Tabloul de bord → Sănătate**. Prezentare generală a stării sistemului în timp real cu 6 carduri: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Card | Ce arată | -| -------------------------- | ------------------------------------------------------------------------------- | -| **Stare sistem** | Uptime, versiune, utilizare a memoriei, director de date | -| **Sănătatea furnizorului** | Stare întrerupător pentru fiecare furnizor (Închis/Deschis/Pe jumătate deschis) | -| **Limite de rate** | Reduceri de reducere a limitei ratei active per cont cu timpul rămas | -| **Blocari active** | Furnizori blocați temporar de politica de blocare | -| **Cache pentru semnături** | Statistici cache de deduplicare (chei active, rata de accesare) | -| **Telemetrie de latență** | agregarea latenței p50/p95/p99 per furnizor | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Sfat profesional:** Pagina Sănătate se reîmprospătează automat la fiecare 10 secunde. Utilizați cardul de întrerupător pentru a identifica furnizorii care se confruntă cu probleme. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/ru/API_REFERENCE.md b/docs/i18n/ru/API_REFERENCE.md index ed38880239..b795722c11 100644 --- a/docs/i18n/ru/API_REFERENCE.md +++ b/docs/i18n/ru/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Справочник по API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Полный справочник по всем конечным точкам API OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Содержание +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## Завершения чата +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Пользовательские заголовки +### Custom Headers -| Заголовок | Направление | Описание | -| ------------------------ | ----------- | ------------------------------------------------ | -| `X-OmniRoute-No-Cache` | Запрос | Установите значение `true` для обхода кеша | -| `X-OmniRoute-Progress` | Запрос | Установите значение `true` для событий прогресса | -| `Idempotency-Key` | Запрос | Ключ дедупликации (окно 5s) | -| `X-Request-Id` | Запрос | Альтернативный ключ дедупликации | -| `X-OmniRoute-Cache` | Ответ | `HIT` или `MISS` (без потоковой передачи) | -| `X-OmniRoute-Idempotent` | Ответ | `true` при дедупликации | -| `X-OmniRoute-Progress` | Ответ | `enabled`, если отслеживание прогресса включено | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Вложения +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Доступные провайдеры: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Генерация изображений +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Доступные провайдеры: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Список моделей +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Конечные точки совместимости +## Compatibility Endpoints -| Метод | Путь | Формат | -| -------- | --------------------------- | ------------------------ | -| ПОСТ | `/v1/chat/completions` | ОпенАИ | -| ПОСТ | `/v1/messages` | Антропный | -| ПОСТ | `/v1/responses` | Ответы OpenAI | -| ПОСТ | `/v1/embeddings` | ОпенАИ | -| ПОСТ | `/v1/images/generations` | ОпенАИ | -| ПОЛУЧИТЬ | `/v1/models` | ОпенАИ | -| ПОСТ | `/v1/messages/count_tokens` | Антропный | -| ПОЛУЧИТЬ | `/v1beta/models` | Близнецы | -| ПОСТ | `/v1beta/models/{...path}` | Близнецы создают контент | -| ПОСТ | `/v1/api/chat` | Оллама | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Маршруты выделенного провайдера +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Префикс провайдера добавляется автоматически, если он отсутствует. Несовпадающие модели возвращают `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Семантический кеш +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Пример ответа: +Response example: ```json { @@ -162,154 +162,164 @@ DELETE /api/cache --- -## Панель управления и управление +## Dashboard & Management -### Аутентификация +### Authentication -| Конечная точка | Метод | Описание | -| ----------------------------- | ------------------ | -------------------------- | -| `/api/auth/login` | ПОСТ | Войти | -| `/api/auth/logout` | ПОСТ | Выйти | -| `/api/settings/require-login` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Переключить требуется вход | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Управление поставщиками +### Provider Management -| Конечная точка | Метод | Описание | -| ---------------------------- | -------------------------- | --------------------------------- | -| `/api/providers` | ПОЛУЧИТЬ/ОТПРАВИТЬ | Список/создание поставщиков | -| `/api/providers/[id]` | ПОЛУЧИТЬ/ПОСТАВИТЬ/УДАЛИТЬ | Управление провайдером | -| `/api/providers/[id]/test` | ПОСТ | Проверка подключения к провайдеру | -| `/api/providers/[id]/models` | ПОЛУЧИТЬ | Список моделей поставщиков | -| `/api/providers/validate` | ПОСТ | Проверка конфигурации провайдера | -| `/api/provider-nodes*` | Разное | Управление узлами провайдера | -| `/api/provider-models` | ПОЛУЧИТЬ/ОТПРАВИТЬ/УДАЛИТЬ | Нестандартные модели | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Потоки OAuth +### OAuth Flows -| Конечная точка | Метод | Описание | -| -------------------------------- | ------ | -------------------------------- | -| `/api/oauth/[provider]/[action]` | Разное | OAuth для конкретного поставщика | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Маршрутизация и конфигурация +### Routing & Config -| Конечная точка | Метод | Описание | -| --------------------- | ------------------ | ------------------------------- | -| `/api/models/alias` | ПОЛУЧИТЬ/ОТПРАВИТЬ | Псевдонимы моделей | -| `/api/models/catalog` | ПОЛУЧИТЬ | Все модели по поставщику + типу | -| `/api/combos*` | Разное | Комбинированное управление | -| `/api/keys*` | Разное | Управление ключами API | -| `/api/pricing` | ПОЛУЧИТЬ | Цены на модели | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Использование и аналитика +### Usage & Analytics -| Конечная точка | Метод | Описание | -| --------------------------- | -------- | ------------------------------------ | -| `/api/usage/history` | ПОЛУЧИТЬ | История использования | -| `/api/usage/logs` | ПОЛУЧИТЬ | Журналы использования | -| `/api/usage/request-logs` | ПОЛУЧИТЬ | Журналы уровня запроса | -| `/api/usage/[connectionId]` | ПОЛУЧИТЬ | Использование для каждого соединения | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Настройки +### Settings -| Конечная точка | Метод | Описание | -| ------------------------------- | ------------------ | ------------------------------------------- | -| `/api/settings` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Общие настройки | -| `/api/settings/proxy` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Конфигурация сетевого прокси | -| `/api/settings/proxy/test` | ПОСТ | Проверить прокси-соединение | -| `/api/settings/ip-filter` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Список разрешенных/блокированных IP-адресов | -| `/api/settings/thinking-budget` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Обоснование бюджета жетона | -| `/api/settings/system-prompt` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Глобальная системная подсказка | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Мониторинг +### Monitoring -| Конечная точка | Метод | Описание | -| ------------------------ | ---------------- | --------------------------------------- | -| `/api/sessions` | ПОЛУЧИТЬ | Отслеживание активных сессий | -| `/api/rate-limits` | ПОЛУЧИТЬ | Ограничения ставок для каждого аккаунта | -| `/api/monitoring/health` | ПОЛУЧИТЬ | Проверка здоровья | -| `/api/cache` | ПОЛУЧИТЬ/УДАЛИТЬ | Статистика кэша / очистить | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Резервное копирование и экспорт/импорт +### Backup & Export/Import -| Конечная точка | Метод | Описание | -| --------------------------- | -------- | ------------------------------------------------------ | -| `/api/db-backups` | ПОЛУЧИТЬ | Список доступных резервных копий | -| `/api/db-backups` | ПУТЬ | Создайте резервную копию вручную | -| `/api/db-backups` | ПОСТ | Восстановление из определенной резервной копии | -| `/api/db-backups/export` | ПОЛУЧИТЬ | Загрузить базу данных в виде файла .sqlite | -| `/api/db-backups/import` | ПОСТ | Загрузите файл .sqlite для замены базы данных | -| `/api/db-backups/exportAll` | ПОЛУЧИТЬ | Загрузите полную резервную копию в виде архива .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Облачная синхронизация +### Cloud Sync -| Конечная точка | Метод | Описание | -| ---------------------- | ------ | ------------------------------- | -| `/api/sync/cloud` | Разное | Операции облачной синхронизации | -| `/api/sync/initialize` | ПОСТ | Инициализировать синхронизацию | -| `/api/cloud/*` | Разное | Облачное управление | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Инструменты CLI +### CLI Tools -| Конечная точка | Метод | Описание | -| ---------------------------------- | -------- | -------------------------- | -| `/api/cli-tools/claude-settings` | ПОЛУЧИТЬ | Статус Клода CLI | -| `/api/cli-tools/codex-settings` | ПОЛУЧИТЬ | Статус CLI Кодекса | -| `/api/cli-tools/droid-settings` | ПОЛУЧИТЬ | Статус Droid CLI | -| `/api/cli-tools/openclaw-settings` | ПОЛУЧИТЬ | Статус OpenClaw CLI | -| `/api/cli-tools/runtime/[toolId]` | ПОЛУЧИТЬ | Общая среда выполнения CLI | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Ответы CLI включают: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Устойчивость и ограничения скорости +### ACP Agents -| Конечная точка | Метод | Описание | -| ----------------------- | ------------------ | ---------------------------------------------- | -| `/api/resilience` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Получить/обновить профили устойчивости | -| `/api/resilience/reset` | ПОСТ | Сброс автоматических выключателей | -| `/api/rate-limits` | ПОЛУЧИТЬ | Статус ограничения ставки для каждого аккаунта | -| `/api/rate-limit` | ПОЛУЧИТЬ | Конфигурация глобального ограничения скорости | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Оценки +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Конечная точка | Метод | Описание | -| -------------- | ------------------ | ----------------------------------------------- | -| `/api/evals` | ПОЛУЧИТЬ/ОТПРАВИТЬ | Получение списка пакетов оценки / запуск оценки | +### Resilience & Rate Limits -### Политики +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Конечная точка | Метод | Описание | -| --------------- | -------------------------- | ----------------------------------- | -| `/api/policies` | ПОЛУЧИТЬ/ОТПРАВИТЬ/УДАЛИТЬ | Управление политиками маршрутизации | +### Evals -### Соответствие +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Конечная точка | Метод | Описание | -| --------------------------- | -------- | ---------------------------------------- | -| `/api/compliance/audit-log` | ПОЛУЧИТЬ | Журнал аудита соответствия (последний N) | +### Policies -### v1beta (совместимость с Близнецами) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Конечная точка | Метод | Описание | -| -------------------------- | -------- | --------------------------------------- | -| `/v1beta/models` | ПОЛУЧИТЬ | Список моделей в формате Gemini | -| `/v1beta/models/{...path}` | ПОСТ | Конечная точка Gemini `generateContent` | +### Compliance -Эти конечные точки отражают формат API Gemini для клиентов, которым требуется встроенная совместимость с Gemini SDK. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### Внутренние/системные API +### v1beta (Gemini-Compatible) -| Конечная точка | Метод | Описание | -| --------------- | -------- | ------------------------------------------------------------------- | -| `/api/init` | ПОЛУЧИТЬ | Проверка инициализации приложения (используется при первом запуске) | -| `/api/tags` | ПОЛУЧИТЬ | Теги моделей, совместимые с Ollama (для клиентов Ollama) | -| `/api/restart` | ПОСТ | Запустить плавный перезапуск сервера | -| `/api/shutdown` | ПОСТ | Запустить корректное завершение работы сервера | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Примечание.** Эти конечные точки используются внутри системы или для совместимости с клиентом Ollama. Обычно они не вызываются конечными пользователями. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Аудио транскрипция +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Транскрибируйте аудиофайлы с помощью Deepgram или AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Запрос:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Ответ:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Поддерживаемые поставщики:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Поддерживаемые форматы:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Совместимость с Олламой +## Ollama Compatibility -Для клиентов, использующих формат API Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Запросы автоматически переводятся между Олламой и внутренними форматами. +Requests are automatically translated between Ollama and internal formats. --- -## Телеметрия +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Ответ:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Бюджет +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Доступность модели +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Обработка запроса +## Request Processing -1. Клиент отправляет запрос на `/v1/*`. -2. Обработчик маршрута вызывает `handleChat`, `handleEmbedding`, `handleAudioTranscription` или `handleImageGeneration`. -3. Модель разрешена (прямой поставщик/модель или псевдоним/комбо) -4. Учетные данные, выбранные из локальной базы данных с фильтрацией доступности учетной записи. -5. Для чата: `handleChatCore` — определение формата, трансляция, проверка кеша, проверка идемпотентности -6. Исполнитель провайдера отправляет восходящий запрос. -7. Ответ переводится обратно в формат клиента (чат) или возвращается в исходном виде (встраивания/изображения/аудио). -8. Запись использования/регистрации -9. Резервный вариант применяется при ошибках в соответствии с правилами комбо. +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Полная ссылка на архитектуру: [link](ARCHITECTURE.md). +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Аутентификация +## Authentication -- Маршруты информационной панели (`/dashboard/*`) используют файл cookie `auth_token`. -- Для входа используется сохраненный хеш пароля; возврат к `INITIAL_PASSWORD` -- `requireLogin` переключается через `/api/settings/require-login` -- Маршруты `/v1/*` дополнительно требуют ключ API носителя, когда `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/ru/ARCHITECTURE.md b/docs/i18n/ru/ARCHITECTURE.md index a3d5f9bb79..258d62df53 100644 --- a/docs/i18n/ru/ARCHITECTURE.md +++ b/docs/i18n/ru/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Архитектура OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Последнее обновление: 18 февраля 2026 г._ +_Last updated: 2026-03-04_ -## Резюме +## Executive Summary -OmniRoute — это локальный шлюз и панель маршрутизации AI, созданные на основе Next.js. -Он предоставляет единую конечную точку, совместимую с OpenAI (`/v1/*`), и маршрутизирует трафик между несколькими вышестоящими поставщиками с трансляцией, резервным копированием, обновлением токена и отслеживанием использования. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Основные возможности: +Core capabilities: -- OpenAI-совместимая поверхность API для CLI/инструментов (28 поставщиков) -- Трансляция запроса/ответа в форматах провайдера. -- Резервный вариант комбо-модели (последовательность из нескольких моделей) -- Резервный вариант на уровне учетной записи (несколько учетных записей для каждого провайдера) -- Управление подключением к поставщику OAuth + API-ключей -- Генерация встраивания через `/v1/embeddings` (6 провайдеров, 9 моделей) -- Генерация изображения через `/v1/images/generations` (4 провайдера, 9 моделей) -- Подумайте о разборе тегов (`...`) для моделей рассуждений. -- Очистка ответов для строгой совместимости OpenAI SDK. -- Нормализация ролей (разработчик→система, система→пользователь) для совместимости между поставщиками. -- Преобразование структурированного вывода (json_schema → Gemini responseSchema) -- Локальное сохранение поставщиков, ключей, псевдонимов, комбинаций, настроек, цен. -- Отслеживание использования/расходов и регистрация запросов -- Дополнительная облачная синхронизация для синхронизации нескольких устройств/состояний. -- Список разрешенных/блокированных IP-адресов для контроля доступа к API. -- Продуманное управление бюджетом (сквозное/автоматическое/настраиваемое/адаптивное) -- Оперативное внедрение глобальной системы -- Отслеживание сеансов и снятие отпечатков пальцев -- Расширенное ограничение скорости для каждой учетной записи с помощью профилей для конкретного поставщика. -- Схема автоматического выключателя для устойчивости поставщика -- Анти-громовая защита стада с блокировкой мьютекса -- Кэш дедупликации запросов на основе сигнатур. -- Уровень домена: доступность модели, правила затрат, резервная политика, политика блокировки. -- Сохранение состояния домена (кэш сквозной записи SQLite для резервных копий, бюджетов, блокировок, автоматических выключателей) -- Механизм политики для централизованной оценки запросов (блокировка → бюджет → резервный вариант) -- Запрос телеметрии с агрегацией задержек p50/p95/p99. -- Идентификатор корреляции (X-Request-Id) для сквозной трассировки. -- Ведение журнала аудита соответствия с возможностью отказа для каждого ключа API. -- Система оценки для обеспечения качества LLM -- Панель управления устойчивостью пользовательского интерфейса с отображением состояния автоматического выключателя в реальном времени. -- Модульные поставщики OAuth (12 отдельных модулей под `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Основная модель времени выполнения: +Primary runtime model: -- Маршруты приложений Next.js в `src/app/api/*` реализуют как API панели мониторинга, так и API совместимости. -- Общее ядро SSE/маршрутизации в `src/sse/*` + `open-sse/*` управляет выполнением поставщика, трансляцией, потоковой передачей, резервным копированием и использованием. +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Область применения и границы +## Scope and Boundaries -### В объеме +### In Scope -- Среда выполнения локального шлюза -- API-интерфейсы управления информационной панелью -- Аутентификация поставщика и обновление токена -- Запросить перевод и потоковую передачу SSE -- Локальное состояние + постоянство использования -- Дополнительная оркестровка облачной синхронизации. +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Выходит за рамки +### Out of Scope -- Реализация облачного сервиса на базе `NEXT_PUBLIC_CLOUD_URL`. -- Соглашение об уровне обслуживания поставщика/плоскость управления вне локального процесса. -- Сами внешние двоичные файлы CLI (Claude CLI, Codex CLI и т. д.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Системный контекст высокого уровня +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,152 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Основные компоненты среды выполнения +## Core Runtime Components -## 1) API и уровень маршрутизации (маршруты приложений Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Основные каталоги: +Main directories: -- `src/app/api/v1/*` и `src/app/api/v1beta/*` для API совместимости. -- `src/app/api/*` для API управления/конфигурации. -- Далее перезаписывает `next.config.mjs` сопоставляет `/v1/*` с `/api/v1/*`. +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Важные пути совместимости: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — включает пользовательские модели с `custom: true`. -- `src/app/api/v1/embeddings/route.ts` — генерация встраивания (6 провайдеров) -- `src/app/api/v1/images/generations/route.ts` — генерация изображений (4+ провайдера, включая Антигравитация/Небиус) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — отдельный чат для каждого провайдера -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — специальные внедрения для каждого провайдера. -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — отдельные изображения для каждого поставщика. +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Домены управления: +Management domains: -- Аутентификация/настройки: `src/app/api/auth/*`, `src/app/api/settings/*`. -- Провайдеры/соединения: `src/app/api/providers*` -- Узлы поставщика: `src/app/api/provider-nodes*` -- Пользовательские модели: `src/app/api/provider-models` (GET/POST/DELETE) -- Каталог моделей: `src/app/api/models/catalog` (GET) -- Конфигурация прокси: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Ключи/псевдонимы/комбо/цены: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`. -- Использование: `src/app/api/usage/*` -- Синхронизация/облако: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Помощники по инструментам CLI: `src/app/api/cli-tools/*`. -- IP-фильтр: `src/app/api/settings/ip-filter` (GET/PUT) -- Мысленный бюджет: `src/app/api/settings/thinking-budget` (GET/PUT) -- Системное приглашение: `src/app/api/settings/system-prompt` (GET/PUT) -- Сессии: `src/app/api/sessions` (GET) -- Ограничения скорости: `src/app/api/rate-limits` (GET) -- Устойчивость: `src/app/api/resilience` (GET/PATCH) — профили провайдера, автоматический выключатель, состояние ограничения скорости. -- Сброс устойчивости: `src/app/api/resilience/reset` (POST) — сброс выключателей + кулдаунов. -- Статистика кэша: `src/app/api/cache/stats` (GET/DELETE) -- Доступность модели: `src/app/api/models/availability` (GET/POST) -- Телеметрия: `src/app/api/telemetry/summary` (GET) -- Бюджет: `src/app/api/usage/budget` (GET/POST) -- Резервные цепочки: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Аудит соответствия: `src/app/api/compliance/audit-log` (GET) -- Оценки: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Политики: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + ядро трансляции +## 2) SSE + Translation Core -Модули основного потока: +Main flow modules: -- Запись: `src/sse/handlers/chat.ts` -- Базовая оркестровка: `open-sse/handlers/chatCore.ts`. -- Адаптеры выполнения поставщика: `open-sse/executors/*` -- Конфигурация обнаружения формата/поставщика: `open-sse/services/provider.ts` -- Анализ/решение модели: `src/sse/services/model.ts`, `open-sse/services/model.ts`. -- Логика возврата учетной записи: `open-sse/services/accountFallback.ts`. -- Реестр переводов: `open-sse/translator/index.ts` -- Преобразования потока: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`. -- Извлечение/нормализация использования: `open-sse/utils/usageTracking.ts` -- Подумайте о парсере тегов: `open-sse/utils/thinkTagParser.ts`. -- Обработчик внедрения: `open-sse/handlers/embeddings.ts` -- Реестр поставщиков встраивания: `open-sse/config/embeddingRegistry.ts`. -- Обработчик генерации изображения: `open-sse/handlers/imageGeneration.ts` -- Реестр поставщика изображений: `open-sse/config/imageRegistry.ts`. -- Обеззараживание ответа: `open-sse/handlers/responseSanitizer.ts`. -- Нормализация ролей: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Сервисы (бизнес-логика): +Services (business logic): -- Выбор/оценка аккаунта: `open-sse/services/accountSelector.ts` -- Управление жизненным циклом контекста: `open-sse/services/contextManager.ts`. -- Применение IP-фильтра: `open-sse/services/ipFilter.ts`. -- Отслеживание сеанса: `open-sse/services/sessionManager.ts` -- Запрос дедупликации: `open-sse/services/signatureCache.ts` -- Подсказка системы: `open-sse/services/systemPrompt.ts` -- Мышление управления бюджетом: `open-sse/services/thinkingBudget.ts` -- Маршрутизация модели с подстановочными знаками: `open-sse/services/wildcardRouter.ts`. -- Управление лимитом скорости: `open-sse/services/rateLimitManager.ts` -- Автоматический выключатель: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Модули доменного уровня: +Domain layer modules: -- Доступность модели: `src/lib/domain/modelAvailability.ts` - – Правила/бюджеты затрат: `src/lib/domain/costRules.ts`. - – Резервная политика: `src/lib/domain/fallbackPolicy.ts`. -- Комбинированный преобразователь: `src/lib/domain/comboResolver.ts` -- Политика блокировки: `src/lib/domain/lockoutPolicy.ts`. -- Механизм политики: `src/domain/policyEngine.ts` — централизованная блокировка → бюджет → резервная оценка. -- Каталог кодов ошибок: `src/lib/domain/errorCodes.ts` -- Идентификатор запроса: `src/lib/domain/requestId.ts` - – Тайм-аут получения: `src/lib/domain/fetchTimeout.ts` -- Запрос телеметрии: `src/lib/domain/requestTelemetry.ts` -- Соответствие/аудит: `src/lib/domain/compliance/index.ts` -- Бегун оценки: `src/lib/domain/evalRunner.ts` -- Сохранение состояния домена: `src/lib/db/domainState.ts` — SQLite CRUD для резервных цепочек, бюджетов, истории затрат, состояния блокировки, автоматических выключателей. +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Модули провайдера OAuth (12 отдельных файлов под `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Индекс реестра: `src/lib/oauth/providers/index.ts` -- Индивидуальные поставщики: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` - — Тонкая оболочка: `src/lib/oauth/providers.ts` — реэкспорт из отдельных модулей. +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Уровень сохранения +## 3) Persistence Layer -Первичное состояние БД: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- файл: `${DATA_DIR}/db.json` (или `$XDG_CONFIG_HOME/omniroute/db.json`, если установлен, иначе `~/.omniroute/db.json`) -- сущности: поставщики Connections, поставщикNodes, modelAliases, комбо, apiKeys, настройки, цены, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Использование БД: +Usage persistence: -- `src/lib/usageDb.ts` -- файлы: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- следует той же политике базового каталога, что и `localDb` (`DATA_DIR`, затем `XDG_CONFIG_HOME/omniroute`, если установлено) -- разложены на целевые подмодули: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -БД состояний домена (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — операции CRUD для состояния домена. -- Таблицы (созданные в `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Шаблон кэша со сквозной записью: карты в памяти являются авторитетными во время выполнения; мутации записываются синхронно в SQLite; состояние восстанавливается из БД при холодном запуске +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Поверхности аутентификации и безопасности +## 4) Auth + Security Surfaces -– Аутентификация файлов cookie информационной панели: `src/proxy.ts`, `src/app/api/auth/login/route.ts`. +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -- Генерация/проверка ключа API: `src/shared/utils/apiKey.ts` -- Секреты поставщика сохранились в записях `providerConnections`. -- Поддержка исходящего прокси через `open-sse/utils/proxyFetch.ts` (переменные окружения) и `open-sse/utils/networkProxy.ts` (настраивается для каждого провайдера или глобально) +## 5) Cloud Sync -## 5) Облачная синхронизация +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -- Инициализация планировщика: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Периодическая задача: `src/shared/services/cloudSyncScheduler.ts`. -- Маршрут управления: `src/app/api/sync/cloud/route.ts` - -## Жизненный цикл запроса (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -305,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Комбо + Последовательность действий при возврате учетной записи +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -335,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Решения об отступлении принимаются `open-sse/services/accountFallback.ts` с использованием кодов состояния и эвристики сообщений об ошибках. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Регистрация OAuth и жизненный цикл обновления токена +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -367,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Обновление во время живого трафика выполняется внутри `open-sse/handlers/chatCore.ts` через исполнителя `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Жизненный цикл облачной синхронизации (включить/синхронизировать/отключить) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -401,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Периодическая синхронизация запускается `CloudSyncScheduler`, когда облако включено. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Модель данных и карта хранилища +## Data Model and Storage Map ```mermaid erDiagram @@ -504,14 +504,14 @@ erDiagram } ``` -Файлы физического хранилища: +Physical storage files: -- основное состояние: `${DATA_DIR}/db.json` (или `$XDG_CONFIG_HOME/omniroute/db.json`, если установлено, иначе `~/.omniroute/db.json`) -- статистика использования: `${DATA_DIR}/usage.json` -- строки журнала запроса: `${DATA_DIR}/log.txt` -- дополнительные сеансы отладки переводчика/запроса: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Топология развертывания +## Deployment Topology ```mermaid flowchart LR @@ -523,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -542,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Сопоставление модулей (критическое для принятия решений) +## Module Mapping (Decision-Critical) -### Модули маршрутов и API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API совместимости. -- `src/app/api/v1/providers/[provider]/*`: выделенные маршруты для каждого поставщика (чат, встраивания, изображения) -- `src/app/api/providers*`: CRUD поставщика, проверка, тестирование -- `src/app/api/provider-nodes*`: управление настраиваемыми совместимыми узлами. -- `src/app/api/provider-models`: управление пользовательскими моделями (CRUD). -- `src/app/api/models/catalog`: API полного каталога моделей (все типы сгруппированы по поставщикам) -- `src/app/api/oauth/*`: потоки OAuth/кода устройства. -- `src/app/api/keys*`: жизненный цикл локального ключа API. -- `src/app/api/models/alias`: управление псевдонимами. -- `src/app/api/combos*`: управление резервными комбинациями. -- `src/app/api/pricing`: переопределение цен для расчета затрат. -- `src/app/api/settings/proxy`: конфигурация прокси (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: проверка исходящего прокси-соединения (POST) -- `src/app/api/usage/*`: использование и журналирование API. -- `src/app/api/sync/*` + `src/app/api/cloud/*`: облачная синхронизация и помощники для работы с облаком. -- `src/app/api/cli-tools/*`: локальные средства записи/проверки конфигурации CLI. -- `src/app/api/settings/ip-filter`: список разрешенных/блокированных IP-адресов (GET/PUT) -- `src/app/api/settings/thinking-budget`: конфигурация бюджета токена (GET/PUT) -- `src/app/api/settings/system-prompt`: глобальная системная подсказка (GET/PUT) -- `src/app/api/sessions`: список активных сеансов (GET) -- `src/app/api/rate-limits`: статус ограничения скорости для каждого аккаунта (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Ядро маршрутизации и выполнения +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: анализ запроса, обработка комбо, цикл выбора учетной записи. -- `open-sse/handlers/chatCore.ts`: трансляция, отправка исполнителя, обработка повтора/обновления, настройка потока. -- `open-sse/executors/*`: поведение сети и формата в зависимости от поставщика. +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Реестр переводов и конвертеры форматов +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: реестр трансляторов и оркестровка. -- Запрос переводчиков: `open-sse/translator/request/*` -- Переводчики ответов: `open-sse/translator/response/*` -- Константы формата: `open-sse/translator/formats.ts`. +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Настойчивость +### Persistence -- `src/lib/localDb.ts`: постоянная конфигурация/состояние -- `src/lib/usageDb.ts`: история использования и журналы повторяющихся запросов. +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Покрытие поставщика-исполнителя (шаблон стратегии) +## Provider Executor Coverage (Strategy Pattern) -У каждого поставщика есть специализированный исполнитель, расширяющий `BaseExecutor` (в `open-sse/executors/base.ts`), который обеспечивает построение URL-адреса, построение заголовка, повторную попытку с экспоненциальной отсрочкой, перехватчики обновления учетных данных и метод оркестрации `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Исполнитель | Поставщик(и) | Специальная обработка | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Динамическая конфигурация URL/заголовка для каждого провайдера | -| `AntigravityExecutor` | Google Антигравитация | Пользовательские идентификаторы проекта/сеанса, повторная попытка после анализа | -| `CodexExecutor` | Кодекс OpenAI | Вводит системные инструкции, заставляет мыслить | -| `CursorExecutor` | Курсор IDE | Протокол ConnectRPC, кодировка Protobuf, подпись запроса через контрольную сумму | -| `GithubExecutor` | Второй пилот GitHub | Обновление токена Copilot, заголовки, имитирующие VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Киро | Бинарный формат AWS EventStream → Преобразование SSE | -| `GeminiCLIExecutor` | Близнецы CLI | Цикл обновления токена Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Все остальные поставщики (включая пользовательские совместимые узлы) используют `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Матрица совместимости поставщиков +## Provider Compatibility Matrix -| Провайдер | Формат | Авторизация | Поток | Непоток | Обновление токена | API использования | -| ------------------- | -------------- | ---------------------------------- | ----------------- | ------- | ----------------- | ---------------------------- | -| Клод | Клод | Ключ API / OAuth | ✅ | ✅ | ✅ | ⚠️ Только администратор | -| Близнецы | близнецы | Ключ API / OAuth | ✅ | ✅ | ✅ | ⚠️ Облачная консоль | -| Близнецы CLI | Близнецы-кли | ОАутент | ✅ | ✅ | ✅ | ⚠️ Облачная консоль | -| Антигравитация | антигравитация | ОАутент | ✅ | ✅ | ✅ | ✅ API с полной квотой | -| ОпенАИ | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| Кодекс | openai-ответы | ОАутент | ✅ принудительный | ❌ | ✅ | ✅ Ограничения ставок | -| Второй пилот GitHub | опенай | OAuth + токен второго пилота | ✅ | ✅ | ✅ | ✅ Снимки квот | -| Курсор | курсор | Пользовательская контрольная сумма | ✅ | ✅ | ❌ | ❌ | -| Киро | Киро | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Ограничения использования | -| Квен | опенай | ОАутент | ✅ | ✅ | ✅ | ⚠️ По запросу | -| iFlow | опенай | OAuth (базовый) | ✅ | ✅ | ✅ | ⚠️ По запросу | -| OpenRouter | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| ГЛМ/Кими/МиниМакс | Клод | API-ключ | ✅ | ✅ | ❌ | ❌ | -| ДипСик | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| Грок | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| xAI (Грок) | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| Мистраль | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| Растерянность | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| Вместе ИИ | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| Фейерверк ИИ | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| Церебра | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| Согласовано | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | -| NVIDIA НИМ | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Охват перевода формата +## Format Translation Coverage -Обнаруженные исходные форматы включают: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Целевые форматы включают: +Target formats include: -- Чат OpenAI/Ответы -- Клод -- Оболочка Gemini/Gemini-CLI/Антигравитация -- Киро -- Курсор +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -В переводах используется **OpenAI в качестве хаб-формата** — все преобразования проходят через OpenAI как промежуточный формат: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Переводы выбираются динамически на основе формы исходной полезной нагрузки и целевого формата поставщика. +Translations are selected dynamically based on source payload shape and provider target format. -Дополнительные уровни обработки в конвейере перевода: +Additional processing layers in the translation pipeline: -- **Обеззараживание ответов** — удаляет нестандартные поля из ответов формата OpenAI (как потоковых, так и непотоковых) для обеспечения строгого соответствия SDK. -- **Нормализация ролей** — преобразует `developer` → `system` для целей, отличных от OpenAI; объединяет `system` → `user` для моделей, отвергающих системную роль (GLM, ERNIE) -- **Извлечение тегов** — анализирует блоки `...` из содержимого в поле `reasoning_content`. -- **Структурированный вывод** — преобразует OpenAI `response_format.json_schema` в Gemini `responseMimeType` + `responseSchema`. +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Поддерживаемые конечные точки API +## Supported API Endpoints -| Конечная точка | Формат | Обработчик | -| -------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------- | -| `POST /v1/chat/completions` | Чат OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Клод Сообщения | Тот же обработчик (определяется автоматически) | -| `POST /v1/responses` | Ответы OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Вложения OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Список моделей | API-маршрут | -| `POST /v1/images/generations` | Изображения OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Список моделей | API-маршрут | -| `POST /v1/providers/{provider}/chat/completions` | Чат OpenAI | Выделенный для каждого поставщика с проверкой модели | -| `POST /v1/providers/{provider}/embeddings` | Вложения OpenAI | Выделенный для каждого поставщика с проверкой модели | -| `POST /v1/providers/{provider}/images/generations` | Изображения OpenAI | Выделенный для каждого поставщика с проверкой модели | -| `POST /v1/messages/count_tokens` | Количество жетонов Клода | API-маршрут | -| `GET /v1/models` | Список моделей OpenAI | Маршрут API (чат + встраивание + изображение + пользовательские модели) | -| `GET /api/models/catalog` | Каталог | Все модели сгруппированы по поставщику + типу | -| `POST /v1beta/models/*:streamGenerateContent` | Уроженец Близнецов | API-маршрут | -| `GET/PUT/DELETE /api/settings/proxy` | Конфигурация прокси | Конфигурация сетевого прокси | -| `POST /api/settings/proxy/test` | Подключение через прокси | Конечная точка проверки работоспособности/подключения прокси-сервера | -| `GET/POST/DELETE /api/provider-models` | Пользовательские модели | Управление пользовательскими моделями для каждого поставщика | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Обработчик обхода +## Bypass Handler -Обработчик обхода (`open-sse/utils/bypassHandler.ts`) перехватывает известные «одноразовые» запросы от Claude CLI — пинги прогрева, извлечение заголовков и подсчет токенов — и возвращает **поддельный ответ** без использования токенов вышестоящего поставщика. Это срабатывает только тогда, когда `User-Agent` содержит `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Конвейер регистрации запросов +## Request Logger Pipeline -Регистратор запросов (`open-sse/utils/requestLogger.ts`) обеспечивает 7-этапный конвейер журналирования отладки, отключенный по умолчанию и включенный через `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Файлы записываются в `/logs//` для каждого сеанса запроса. +Files are written to `/logs//` for each request session. -## Режимы отказов и устойчивость +## Failure Modes and Resilience -## 1) Доступность учетной записи/провайдера +## 1) Account/Provider Availability -- Время восстановления учетной записи провайдера при ошибках переходного процесса/скорости/авторизации -- резервный аккаунт перед неудачным запросом -- откат комбинированной модели, когда текущий путь модели/провайдера исчерпан. +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Срок действия токена +## 2) Token Expiry -- предварительная проверка и обновление с повтором для обновляемых поставщиков -- Повторная попытка 401/403 после попытки обновления по основному пути. +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Безопасность трансляции +## 3) Stream Safety -- контроллер потока с поддержкой отключения -- поток перевода со сбросом конца потока и обработкой `[DONE]` -- запасной вариант оценки использования, когда метаданные об использовании поставщика отсутствуют. +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Деградация облачной синхронизации +## 4) Cloud Sync Degradation -- Обнаруживаются ошибки синхронизации, но локальное выполнение продолжается. -- планировщик имеет логику с возможностью повторных попыток, но периодическое выполнение в настоящее время по умолчанию вызывает синхронизацию с одной попыткой. +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Целостность данных +## 5) Data Integrity -- Миграция/восстановление формы БД для отсутствующих ключей. -- повреждены средства защиты сброса JSON для localDb и useDb. +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Наблюдаемость и оперативные сигналы +## Observability and Operational Signals -Источники видимости во время выполнения: +Runtime visibility sources: -- логи консоли от `src/sse/utils/logger.ts` -- агрегаты использования по запросу в `usage.json` -- журнал статуса текстового запроса в `log.txt` -- дополнительные журналы глубоких запросов/трансляций под `logs/`, когда `ENABLE_REQUEST_LOGS=true` -- конечные точки использования информационной панели (`/api/usage/*`) для использования пользовательского интерфейса. +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Границы, чувствительные к безопасности +## Security-Sensitive Boundaries -- Секрет JWT (`JWT_SECRET`) обеспечивает проверку/подпись файлов cookie сеанса информационной панели. -- Первоначальный резервный пароль (`INITIAL_PASSWORD`, по умолчанию `123456`) должен быть переопределен в реальных развертываниях. -- Секрет HMAC ключа API (`API_KEY_SECRET`) защищает сгенерированный формат локального ключа API. -- Секреты поставщика (ключи/токены API) сохраняются в локальной базе данных и должны быть защищены на уровне файловой системы. -- Конечные точки облачной синхронизации полагаются на аутентификацию по ключу API + семантику идентификатора машины. +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Матрица среды и времени выполнения +## Environment and Runtime Matrix -Переменные среды, активно используемые кодом: +Environment variables actively used by code: -- Приложение/авторизация: `JWT_SECRET`, `INITIAL_PASSWORD`. -- Хранилище: `DATA_DIR` -- Совместимое поведение узла: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`. -- Дополнительное переопределение базы хранилища (Linux/macOS, если `DATA_DIR` не установлено): `XDG_CONFIG_HOME` -- Хеширование безопасности: `API_KEY_SECRET`, `MACHINE_ID_SALT`. -- Ведение журнала: `ENABLE_REQUEST_LOGS` - – URL-адрес синхронизации/облака: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`. -- Исходящий прокси: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` и варианты в нижнем регистре. -- Флаги функций SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`. -- Помощники платформы/среды выполнения (не конфигурация для конкретного приложения): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`. +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Известные архитектурные заметки +## Known Architectural Notes -1. `usageDb` и `localDb` теперь используют одну и ту же базовую политику каталогов (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) с миграцией устаревших файлов. -2. `/api/v1/route.ts` возвращает список статических моделей и не является основным источником моделей, используемым `/v1/models`. -3. Регистратор запросов записывает полные заголовки/тело, если включен; рассматривать каталог журналов как конфиденциальный. -4. Поведение облака зависит от правильного `NEXT_PUBLIC_BASE_URL` и доступности конечной точки облака. -5. Каталог `open-sse/` публикуется как `@omniroute/open-sse` **пакет рабочей области npm**. Исходный код импортирует его через `@omniroute/open-sse/...` (разрешается Next.js `transpilePackages`). Пути к файлам в этом документе по-прежнему используют имя каталога `open-sse/` для обеспечения единообразия. -6. В диаграммах на панели мониторинга используются **Recharts** (на основе SVG) для доступных интерактивных аналитических визуализаций (столбчатые диаграммы использования модели, таблицы разбивки поставщиков с показателями успешности). -7. В тестах E2E используется **Playwright** (`tests/e2e/`), запускаемый через `npm run test:e2e`. Модульные тесты используют **средство выполнения тестов Node.js** (`tests/unit/`), запускаемое через `npm run test:plan3`. Исходный код `src/` — **TypeScript** (`.ts`/`.tsx`); рабочая область `open-sse/` остаётся JavaScript (`.js`). -8. Страница настроек разделена на 5 вкладок: Безопасность, Маршрутизация (6 глобальных стратегий: сначала заполнение, циклический анализ, p2c, случайная, наименее используемая, оптимизация затрат), Устойчивость (редактируемые ограничения скорости, автоматический выключатель, политики), AI (продумывание бюджета, системные подсказки, кеш подсказок), Дополнительно (прокси). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Контрольный список оперативной проверки +## Operational Verification Checklist -- Сборка из исходного кода: `npm run build`. -- Создайте образ Docker: `docker build -t omniroute .`. -- Запустите службу и проверьте: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- Целевой базовый URL-адрес CLI должен быть `http://:20128/v1`, когда `PORT=20128`. +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ru/CODEBASE_DOCUMENTATION.md b/docs/i18n/ru/CODEBASE_DOCUMENTATION.md index 16f253f574..303880c198 100644 --- a/docs/i18n/ru/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/ru/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Документация по кодовой базе +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Подробное руководство для начинающих по **omniroute** прокси-маршрутизатору с искусственным интеллектом, работающим от нескольких поставщиков. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Что такое омнирут? +## 1. What Is omniroute? -omniroute — это **прокси-маршрутизатор**, который находится между клиентами ИИ (Claude CLI, Codex, Cursor IDE и т. д.) и поставщиками ИИ (Anthropic, Google, OpenAI, AWS, GitHub и т. д.). Это решает одну большую проблему: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Различные клиенты ИИ говорят на разных «языках» (форматах API), и разные поставщики ИИ тоже ожидают разных «языков».** omniroute автоматически переводит между ними. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Думайте об этом как об универсальном переводчике в Организации Объединенных Наций: любой делегат может говорить на любом языке, а переводчик переводит его для любого другого делегата. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Обзор архитектуры +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Основной принцип: комплексный перевод +### Core Principle: Hub-and-Spoke Translation -Вся трансляция формата проходит через **формат OpenAI в качестве концентратора**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Это означает, что вам нужно только **N трансляторов** (по одному на каждый формат) вместо **N²** (каждая пара). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Структура проекта +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Разбивка по модулям +## 4. Module-by-Module Breakdown -### 4.1 Конфигурация (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**Единый источник достоверной информации** для всех конфигураций провайдеров. +The **single source of truth** for all provider configuration. -| Файл | Цель | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | Объект `PROVIDERS` с базовыми URL-адресами, учетными данными OAuth (по умолчанию), заголовками и системными приглашениями по умолчанию для каждого поставщика. Также определяет `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` и `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Загружает внешние учетные данные из `data/provider-credentials.json` и объединяет их с жестко запрограммированными значениями по умолчанию в `PROVIDERS`. Сохраняет секреты вне контроля версий, сохраняя при этом обратную совместимость. | -| `providerModels.ts` | Центральный реестр моделей: псевдонимы поставщиков карт → идентификаторы моделей. Такие функции, как `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Системные инструкции, внедряемые в запросы Кодекса (ограничения редактирования, правила песочницы, политики утверждения). | -| `defaultThinkingSignature.ts` | «Мыслящие» подписи по умолчанию для моделей Claude и Gemini. | -| `ollamaModels.ts` | Определение схемы для локальных моделей Олламы (имя, размер, семейство, квантование). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Процесс загрузки учетных данных +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Исполнители (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Исполнители инкапсулируют **логику, специфичную для поставщика**, используя **Шаблон стратегии**. Каждый исполнитель переопределяет базовые методы по мере необходимости. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Исполнитель | Провайдер | Ключевые специализации | -| ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `base.ts` | — | Абстрактная база: построение URL-адресов, заголовки, логика повторов, обновление учетных данных | -| `default.ts` | Клод, Близнецы, OpenAI, GLM, Кими, МиниМакс | Обновление общего токена OAuth для стандартных поставщиков | -| `antigravity.ts` | Облачный код Google | Генерация идентификатора проекта/сеанса, резервное копирование нескольких URL-адресов, настраиваемый повторный анализ сообщений об ошибках («сброс через 2 часа 7 минут 23 секунды») | -| `cursor.ts` | Курсор IDE | **Самое сложное**: проверка подлинности по контрольной сумме SHA-256, кодирование запроса Protobuf, двоичный поток событий → анализ ответа SSE | -| `codex.ts` | Кодекс OpenAI | Вводит системные инструкции, управляет уровнями мышления, удаляет неподдерживаемые параметры | -| `gemini-cli.ts` | Интерфейс командной строки Google Gemini | Создание собственного URL-адреса (`streamGenerateContent`), обновление токена Google OAuth | -| `github.ts` | Второй пилот GitHub | Система двух токенов (GitHub OAuth + токен Copilot), имитация заголовка VSCode | -| `kiro.ts` | AWS CodeWhisperer | Бинарный анализ AWS EventStream, кадры событий AMZN, оценка токенов | -| `index.ts` | — | Фабрика: имя поставщика карт → класс исполнителя, с резервным вариантом по умолчанию | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Обработчики (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**Уровень оркестрации** — координирует трансляцию, выполнение, потоковую передачу и обработку ошибок. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Файл | Цель | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Центральный оркестратор** (~600 строк). Обрабатывает полный жизненный цикл запроса: обнаружение формата → трансляция → отправка исполнителя → потоковый/непоточный ответ → обновление токена → обработка ошибок → журналирование использования. | -| `responsesHandler.ts` | Адаптер для API ответов OpenAI: преобразует формат ответов → Завершения чата → отправляет в `chatCore` → преобразует SSE обратно в формат ответов. | -| `embeddings.ts` | Обработчик генерации внедрения: разрешает модель внедрения → поставщик, отправляет в API поставщика, возвращает ответ на внедрение, совместимый с OpenAI. Поддерживает 6+ провайдеров. | -| `imageGeneration.ts` | Обработчик генерации изображений: определяет модель изображения → поставщик, поддерживает режимы OpenAI-совместимый, Gemini-image (Антигравитация) и резервный режим (Nebius). Возвращает изображения в формате Base64 или URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Жизненный цикл запроса (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Услуги (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Бизнес-логика, поддерживающая обработчики и исполнители. +Business logic that supports the handlers and executors. -| Файл | Цель | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Обнаружение формата** (`detectFormat`): анализирует структуру тела запроса для определения форматов Claude/OpenAI/Gemini/Antigravity/Responses (включая эвристику `max_tokens` для Claude). А также: построение URL, построение заголовков, нормализация конфигурации мышления. Поддерживает динамических поставщиков `openai-compatible-*` и `anthropic-compatible-*`. | -| `model.ts` | Анализ строки модели (`claude/model-name` → `{provider: "claude", model: "model-name"}`), разрешение псевдонимов с обнаружением коллизий, очистка ввода (отклоняет обход пути/управляющие символы) и разрешение информации модели с поддержкой асинхронного метода получения псевдонимов. | -| `accountFallback.ts` | Обработка ограничения скорости: экспоненциальная отсрочка (1 с → 2 с → 4 с → максимум 2 минуты), управление временем восстановления учетной записи, классификация ошибок (какие ошибки вызывают откат, а какие нет). | -| `tokenRefresh.ts` | Обновление токена OAuth для **каждого поставщика**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + двойной токен Copilot), Kiro (AWS SSO OIDC + Social Auth). Включает в себя кэш дедупликации обещаний в реальном времени и повторные попытки с экспоненциальной задержкой. | -| `combo.ts` | **Комбо-модели**: цепочки резервных моделей. Если модель A дает сбой из-за ошибки, допускающей возврат, попробуйте модель B, затем C и т. д. Возвращает фактические коды состояния восходящего потока. | -| `usage.ts` | Извлекает данные о квотах/использовании из API-интерфейсов провайдера (квоты GitHub Copilot, квоты модели Antigravity, ограничения скорости Кодекса, разбивка использования Kiro, настройки Claude). | -| `accountSelector.ts` | Интеллектуальный выбор учетной записи с алгоритмом оценки: учитывает приоритет, состояние здоровья, позицию циклического перебора и состояние перезарядки, чтобы выбрать оптимальную учетную запись для каждого запроса. | -| `contextManager.ts` | Управление жизненным циклом контекста запроса: создает и отслеживает объекты контекста каждого запроса с метаданными (идентификатор запроса, временные метки, информация о поставщике) для отладки и журналирования. | -| `ipFilter.ts` | Контроль доступа на основе IP: поддерживает режимы белого и черного списка. Проверяет IP-адрес клиента на соответствие настроенным правилам перед обработкой запросов API. | -| `sessionManager.ts` | Отслеживание сеансов с помощью снятия отпечатков пальцев клиентов: отслеживает активные сеансы с использованием хешированных идентификаторов клиентов, отслеживает количество запросов и предоставляет метрики сеансов. | -| `signatureCache.ts` | Кэш дедупликации на основе сигнатур запросов: предотвращает дублирование запросов за счет кэширования сигнатур последних запросов и возврата кэшированных ответов на идентичные запросы в течение определенного временного окна. | -| `systemPrompt.ts` | Глобальное внедрение системного приглашения: добавляет или добавляет настраиваемое системное приглашение ко всем запросам с обработкой совместимости для каждого поставщика. | -| `thinkingBudget.ts` | Управление бюджетом токенов рассуждения: поддерживает сквозной, автоматический (конфигурация с ограничением мышления), пользовательский (фиксированный бюджет) и адаптивный (масштабируемый по сложности) режимы управления токенами мышления/рассуждения. | -| `wildcardRouter.ts` | Маршрутизация шаблонов модели с подстановочными знаками: разрешает шаблоны с подстановочными знаками (например, `*/claude-*`) для конкретных пар поставщик/модель на основе доступности и приоритета. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Дедупликация обновления токена +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Резервный конечный автомат учетной записи +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Комбо-цепочка моделей +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Переводчик (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**Механизм перевода форматов**, использующий систему саморегистрирующихся плагинов. +The **format translation engine** using a self-registering plugin system. -#### Архитектура +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Каталог | Файлы | Описание | -| ------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 переводчиков | Преобразование тел запросов между форматами. Каждый файл самостоятельно регистрируется через `register(from, to, fn)` при импорте. | -| `response/` | 7 переводчиков | Преобразование фрагментов потокового ответа между форматами. Обрабатывает типы событий SSE, блоки мышления, вызовы инструментов. | -| `helpers/` | 6 помощников | Общие утилиты: `claudeHelper` (извлечение системных подсказок, конфигурация мышления), `geminiHelper` (сопоставление частей/содержимого), `openaiHelper` (фильтрация формата), `toolCallHelper` (генерация идентификатора, вставка отсутствующего ответа), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Механизм перевода: `translateRequest()`, `translateResponse()`, управление состоянием, реестр. | -| `formats.ts` | — | Константы формата: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Ключевой дизайн: саморегистрирующиеся плагины +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Утилиты (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Файл | Цель | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Построение ответов об ошибках (формат, совместимый с OpenAI), анализ ошибок восходящего потока, извлечение времени повтора Антигравитации из сообщений об ошибках, потоковая передача ошибок SSE. | -| `stream.ts` | **SSE Transform Stream** — основной конвейер потоковой передачи. Два режима: `TRANSLATE` (полноформатный перевод) и `PASSTHROUGH` (нормализация + использование извлечения). Управляет буферизацией фрагментов, оценкой использования, отслеживанием длины контента. Экземпляры попоточного кодировщика/декодера избегают общего состояния. | -| `streamHelpers.ts` | Утилиты SSE низкого уровня: `parseSSELine` (толерантный к пробелам), `hasValuableContent` (фильтрует пустые фрагменты для OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (сериализация SSE с учетом формата с очисткой `perf_metrics`). | -| `usageTracking.ts` | Извлечение использования токенов из любого формата (Claude/OpenAI/Gemini/Responses), оценка с помощью отдельных соотношений инструмента/сообщения на токен, добавление буфера (запас безопасности 2000 токенов), фильтрация полей для конкретного формата, ведение журнала консоли с цветами ANSI. | -| `requestLogger.ts` | Ведение журнала запросов на основе файлов (согласие через `ENABLE_REQUEST_LOGS=true`). Создает папки сеансов с пронумерованными файлами: `1_req_client.json` → `7_res_client.txt`. Весь ввод-вывод является асинхронным (выстрелил и забыл). Маскирует чувствительные заголовки. | -| `bypassHandler.ts` | Перехватывает определенные шаблоны из Claude CLI (извлечение заголовков, прогрев, подсчет) и возвращает поддельные ответы без вызова какого-либо провайдера. Поддерживает как потоковую, так и непотоковую передачу. Намеренно ограничено областью действия Claude CLI. | -| `networkProxy.ts` | Разрешает URL-адрес исходящего прокси-сервера для данного поставщика с приоритетом: конфигурация конкретного поставщика → глобальная конфигурация → переменные среды (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Поддерживает исключения `NO_PROXY`. Кэширует конфиг на 30 секунд. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Потоковый конвейер SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Структура сеанса регистратора запросов +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Прикладной уровень (`src/`) +### 4.7 Application Layer (`src/`) -| Каталог | Цель | -| ------------- | ------------------------------------------------------------------------------------------ | -| `src/app/` | Веб-интерфейс, маршруты API, промежуточное ПО Express, обработчики обратного вызова OAuth | -| `src/lib/` | Доступ к базе данных (`localDb.ts`, `usageDb.ts`), аутентификация, общий доступ | -| `src/mitm/` | Прокси-утилиты «Человек посередине» для перехвата трафика провайдера | -| `src/models/` | Определения модели базы данных | -| `src/shared/` | Обертки вокруг функций open-sse (поставщик, поток, ошибка и т. д.) | -| `src/sse/` | Обработчики конечных точек SSE, которые подключают библиотеку open-sse к маршрутам Express | -| `src/store/` | Управление состоянием приложения | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Известные маршруты API +#### Notable API Routes -| Маршрут | Методы | Цель | -| --------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | ПОЛУЧИТЬ/ОТПРАВИТЬ/УДАЛИТЬ | CRUD для пользовательских моделей для каждого поставщика | -| `/api/models/catalog` | ПОЛУЧИТЬ | Агрегированный каталог всех моделей (чат, встраивание, изображение, кастом), сгруппированный по поставщикам | -| `/api/settings/proxy` | ПОЛУЧИТЬ/ПОСТАВИТЬ/УДАЛИТЬ | Иерархическая конфигурация исходящего прокси-сервера (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | ПОСТ | Проверяет подключение прокси-сервера и возвращает общедоступный IP-адрес и задержку | -| `/v1/providers/[provider]/chat/completions` | ПОСТ | Специальное завершение чата для каждого поставщика с проверкой модели | -| `/v1/providers/[provider]/embeddings` | ПОСТ | Выделенные внедрения для каждого поставщика с проверкой модели | -| `/v1/providers/[provider]/images/generations` | ПОСТ | Специальное создание изображений для каждого поставщика с проверкой модели | -| `/api/settings/ip-filter` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Управление списком разрешенных/черных IP-адресов | -| `/api/settings/thinking-budget` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Конфигурация бюджета токена обоснования (сквозной/автоматический/пользовательский/адаптивный) | -| `/api/settings/system-prompt` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Глобальная система быстрого внедрения для всех запросов | -| `/api/sessions` | ПОЛУЧИТЬ | Отслеживание активных сессий и метрики | -| `/api/rate-limits` | ПОЛУЧИТЬ | Статус ограничения ставки для каждого аккаунта | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Ключевые шаблоны проектирования +## 5. Key Design Patterns -### 5.1 Координатный перевод +### 5.1 Hub-and-Spoke Translation -Все форматы преобразуются через **формат OpenAI в качестве концентратора**. Для добавления нового провайдера требуется написать только **одну пару** трансляторов (в/из OpenAI), а не N пар. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Шаблон стратегии исполнителя +### 5.2 Executor Strategy Pattern -У каждого поставщика есть выделенный класс исполнителя, унаследованный от `BaseExecutor`. Фабрика в `executors/index.ts` выбирает правильный вариант во время выполнения. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Система саморегистрации плагинов +### 5.3 Self-Registering Plugin System -Модули переводчика регистрируются при импорте через `register()`. Добавление нового переводчика — это просто создание файла и его импорт. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Резервный аккаунт с экспоненциальным откатом +### 5.4 Account Fallback with Exponential Backoff -Когда провайдер возвращает 429/401/500, система может переключиться на следующую учетную запись, применяя экспоненциальное время восстановления (1 с → 2 с → 4 с → максимум 2 минуты). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Цепочки комбо-моделей +### 5.5 Combo Model Chains -«Комбо» группирует несколько строк `provider/model`. Если первое не удалось, автоматически переходите к следующему. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Потоковая трансляция с сохранением состояния +### 5.6 Stateful Streaming Translation -Трансляция ответов поддерживает состояние блоков SSE (отслеживание мыслительных блоков, накопление вызовов инструментов, индексирование блоков контента) с помощью механизма `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Использование буфера безопасности +### 5.7 Usage Safety Buffer -К сообщаемому использованию добавляется буфер на 2000 токенов, чтобы клиенты не превышали ограничения контекстного окна из-за накладных расходов на системные подсказки и преобразование формата. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Поддерживаемые форматы +## 6. Supported Formats -| Формат | Направление | Идентификатор | -| ---------------------------------------- | --------------- | ------------------ | -| Завершения чата OpenAI | источник + цель | `openai` | -| API ответов OpenAI | источник + цель | `openai-responses` | -| Антропный Клод | источник + цель | `claude` | -| Google Близнецы | источник + цель | `gemini` | -| Интерфейс командной строки Google Gemini | только цель | `gemini-cli` | -| Антигравитация | источник + цель | `antigravity` | -| AWS Киро | только цель | `kiro` | -| Курсор | только цель | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Поддерживаемые провайдеры +## 7. Supported Providers -| Провайдер | Метод аутентификации | Исполнитель | Ключевые примечания | -| ---------------------------------------- | -------------------------- | -------------- | ------------------------------------------------------------------------ | -| Антропный Клод | Ключ API или OAuth | По умолчанию | Использует заголовок `x-api-key` | -| Google Близнецы | Ключ API или OAuth | По умолчанию | Использует заголовок `x-goog-api-key` | -| Интерфейс командной строки Google Gemini | ОАутент | БлизнецыCLI | Использует конечную точку `streamGenerateContent` | -| Антигравитация | ОАутент | Антигравитация | Резервный вариант нескольких URL-адресов, индивидуальный анализ повторов | -| ОпенАИ | API-ключ | По умолчанию | Проверка подлинности стандартного носителя | -| Кодекс | ОАутент | Кодекс | Вводит системные инструкции, управляет мышлением | -| Второй пилот GitHub | OAuth + токен Copilot | Гитхаб | Двойной токен, имитация заголовка VSCode | -| Киро (AWS) | AWS SSO OIDC или Social | Киро | Анализ двоичного потока событий | -| Курсор IDE | Проверка контрольной суммы | Курсор | Кодирование Protobuf, контрольные суммы SHA-256 | -| Квен | ОАутент | По умолчанию | Стандартная аутентификация | -| iFlow | OAuth (базовый + носитель) | По умолчанию | Заголовок двойной аутентификации | -| OpenRouter | API-ключ | По умолчанию | Проверка подлинности стандартного носителя | -| ГЛМ, Кими, МиниМакс | API-ключ | По умолчанию | Совместимость с Claude, используйте `x-api-key` | -| `openai-compatible-*` | API-ключ | По умолчанию | Динамический: любая конечная точка, совместимая с OpenAI | -| `anthropic-compatible-*` | API-ключ | По умолчанию | Динамический: любая конечная точка, совместимая с Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Сводная информация о потоке данных +## 8. Data Flow Summary -### Запрос потоковой передачи +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Непотоковый запрос +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Обход потока (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/ru/FEATURES.md b/docs/i18n/ru/FEATURES.md index 9d070fec4b..82cc73b67b 100644 --- a/docs/i18n/ru/FEATURES.md +++ b/docs/i18n/ru/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Галерея функций информационной панели +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Визуальное руководство по каждому разделу панели управления OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Провайдеры +## 🔌 Providers -Управляйте соединениями с поставщиками ИИ: поставщиками OAuth (Claude Code, Codex, Gemini CLI), поставщиками ключей API (Groq, DeepSeek, OpenRouter) и бесплатными поставщиками (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Комбо +## 🎨 Combos -Создавайте комбинации маршрутизации моделей с помощью шести стратегий: «сначала заполнить», «циклический», «степень двух вариантов», «случайный», «наименее используемый» и «оптимизированный по затратам». Каждая комбинация объединяет несколько моделей с автоматическим возвратом. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Аналитика +## 📊 Analytics -Комплексная аналитика использования с использованием токенов, оценками затрат, тепловыми картами активности, еженедельными диаграммами распределения и разбивкой по каждому провайдеру. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Состояние системы +## 🏥 System Health -Мониторинг в режиме реального времени: время безотказной работы, память, версия, процентили задержки (p50/p95/p99), статистика кэша и состояния автоматического выключателя поставщика. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Игровая площадка переводчика +## 🔧 Translator Playground -Четыре режима отладки переводов API: **Игровая площадка** (конвертер форматов), **Тестер чата** (живые запросы), **Тестовый стенд** (пакетные тесты) и **Живой монитор** (поток в реальном времени). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Настройки +## 🎮 Model Playground _(v2.0.9+)_ -Общие настройки, системное хранилище, управление резервным копированием (экспорт/импорт базы данных), внешний вид (темный/светлый режим), безопасность (включая защиту конечных точек API и блокировку настраиваемых провайдеров), маршрутизация, устойчивость и расширенная настройка. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Инструменты CLI +## 🔧 CLI Tools -Конфигурация инструментов искусственного кодирования одним щелчком мыши: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code и Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Журналы запросов +## 🤖 CLI Agents _(v2.0.11+)_ -Регистрация запросов в режиме реального времени с фильтрацией по поставщику, модели, учетной записи и ключу API. Показывает коды состояния, использование токена, задержку и сведения об ответе. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Конечная точка API +## 🌐 API Endpoint -Ваша унифицированная конечная точка API с разбивкой возможностей: завершение чата, внедрение, создание изображений, изменение рейтинга, расшифровка аудио и зарегистрированные ключи API. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ru/TROUBLESHOOTING.md b/docs/i18n/ru/TROUBLESHOOTING.md index 94723eb4af..120092d63c 100644 --- a/docs/i18n/ru/TROUBLESHOOTING.md +++ b/docs/i18n/ru/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Устранение неполадок +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Распространенные проблемы и решения OmniRoute. +Common problems and solutions for OmniRoute. --- -## Быстрые исправления +## Quick Fixes -| Проблема | Решение | -| --------------------------------------------- | ------------------------------------------------------------------------------ | -| Первый вход в систему не работает | Проверьте `INITIAL_PASSWORD` в `.env` (по умолчанию: `123456`) | -| Панель управления открывается не на тот порт | Установите `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Никакие запросы не регистрируются под `logs/` | Установите `ENABLE_REQUEST_LOGS=true` | -| EACCES: в разрешении отказано | Установите `DATA_DIR=/path/to/writable/dir` для переопределения `~/.omniroute` | -| Стратегия маршрутизации не сохраняется | Обновление до версии 1.4.11+ (исправление схемы Zod для сохранения настроек) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Проблемы с провайдером +## Provider Issues -### "Языковая модель не предоставила сообщения" +### "Language model did not provide messages" -**Причина:** квота поставщика исчерпана. +**Cause:** Provider quota exhausted. -**Исправлено:** +**Fix:** -1. Проверьте трекер квот на панели управления. -2. Используйте комбо с запасными уровнями -3. Перейдите на более дешевый/бесплатный уровень. +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Ограничение скорости +### Rate Limiting -**Причина:** квота подписки исчерпана. +**Cause:** Subscription quota exhausted. -**Исправлено:** +**Fix:** -- Добавить резервный вариант: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`. -- Используйте GLM/MiniMax в качестве дешевой резервной копии. +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Срок действия токена OAuth истек +### OAuth Token Expired -OmniRoute автоматически обновляет токены. Если проблемы сохраняются: +OmniRoute auto-refreshes tokens. If issues persist: -1. Панель управления → Провайдер → Переподключиться. -2. Удалить и заново добавить подключение провайдера +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Проблемы с облаком +## Cloud Issues -### Ошибки облачной синхронизации +### Cloud Sync Errors -1. Убедитесь, что `BASE_URL` указывает на ваш работающий экземпляр (например, `http://localhost:20128`). -2. Убедитесь, что `CLOUD_URL` указывает на конечную точку вашего облака (например, `https://omniroute.dev`). -3. Сохраняйте значения `NEXT_PUBLIC_*` в соответствии со значениями на стороне сервера. +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Облако `stream=false` Возвращает 500 +### Cloud `stream=false` Returns 500 -**Симптом:** `Unexpected token 'd'...` на конечной точке облака для вызовов без потоковой передачи. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Причина:** Восходящий поток возвращает полезные данные SSE, хотя клиент ожидает JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Решение:** используйте `stream=true` для прямых вызовов из облака. Локальная среда выполнения включает резервный вариант SSE→JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Облако сообщает о подключении, но «неверный ключ API» +### Cloud Says Connected but "Invalid API key" -1. Создайте новый ключ на локальной панели управления (`/api/keys`). -2. Запустите облачную синхронизацию: Включить «Облако» → «Синхронизировать сейчас». -3. Старые/несинхронизированные ключи по-прежнему могут возвращать `401` в облаке. +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Проблемы с докером +## Docker Issues -### Инструмент CLI показывает, что не установлен +### CLI Tool Shows Not Installed -1. Проверьте поля времени выполнения: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`. -2. Для портативного режима: используйте целевой образ `runner-cli` (входящие в комплект CLI). -3. Для режима монтирования хоста: установите `CLI_EXTRA_PATHS` и смонтируйте каталог bin хоста как доступный только для чтения. -4. Если `installed=true` и `runnable=false`: двоичный файл найден, но проверка работоспособности не удалась. +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Быстрая проверка времени выполнения +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Проблемы со стоимостью +## Cost Issues -### Высокие затраты +### High Costs -1. Проверьте статистику использования в Личном кабинете → Использование. -2. Переключите основную модель на GLM/MiniMax. -3. Используйте уровень бесплатного пользования (Gemini CLI, iFlow) для некритических задач. -4. Установите бюджеты затрат для каждого ключа API: Панель управления → Ключи API → Бюджет. +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Отладка +## Debugging -### Включить журналы запросов +### Enable Request Logs -Установите `ENABLE_REQUEST_LOGS=true` в файле `.env`. Журналы отображаются в каталоге `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Проверка работоспособности поставщика +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Хранилище времени выполнения +### Runtime Storage -- Основное состояние: `${DATA_DIR}/db.json` (провайдеры, комбинации, псевдонимы, ключи, настройки) -- Использование: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Запрос журналов: `/logs/...` (при `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Проблемы с автоматическим выключателем +## Circuit Breaker Issues -### Поставщик застрял в состоянии OPEN +### Provider stuck in OPEN state -Когда автоматический выключатель провайдера разомкнут, запросы блокируются до истечения времени восстановления. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Исправлено:** +**Fix:** -1. Перейдите в **Панель управления → Настройки → Устойчивость**. -2. Проверьте карту автоматического выключателя соответствующего поставщика. -3. Нажмите **Сбросить все**, чтобы очистить все выключатели, или подождите, пока истечет время восстановления. -4. Перед сбросом убедитесь, что поставщик действительно доступен. +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Поставщик продолжает отключать автоматический выключатель +### Provider keeps tripping the circuit breaker -Если провайдер неоднократно переходит в состояние OPEN: +If a provider repeatedly enters OPEN state: -1. Проверьте **Панель управления → Состояние → Состояние поставщика**, чтобы узнать о шаблоне сбоя. -2. Перейдите в **Настройки → Устойчивость → Профили поставщиков** и увеличьте порог отказа. -3. Проверьте, не изменил ли провайдер лимиты API или требует повторной аутентификации. -4. Проверьте телеметрию задержки — высокая задержка может привести к сбоям из-за тайм-аута. +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Проблемы с транскрипцией аудио +## Audio Transcription Issues -### Ошибка «Неподдерживаемая модель» +### "Unsupported model" error -– Убедитесь, что вы используете правильный префикс: `deepgram/nova-3` или `assemblyai/best`. -– Убедитесь, что провайдер подключен в **Панель управления → Провайдеры**. +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Транскрипция возвращает пустое значение или завершается с ошибкой +### Transcription returns empty or fails -- Проверьте поддерживаемые аудиоформаты: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. - – Убедитесь, что размер файла находится в пределах ограничений поставщика (обычно < 25 МБ). -- Проверьте действительность ключа API провайдера в карточке провайдера. +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Отладка переводчика +## Translator Debugging -Используйте **Панель управления → Переводчик** для устранения проблем с переводом формата: +Use **Dashboard → Translator** to debug format translation issues: -| Режим | Когда использовать | -| ----------------------- | ------------------------------------------------------------------------------------------------------------- | -| **Детская площадка** | Сравните форматы ввода/вывода параллельно — вставьте ошибочный запрос, чтобы посмотреть, как он преобразуется | -| **Тестер чата** | Отправляйте живые сообщения и проверяйте всю полезную нагрузку запроса/ответа, включая заголовки | -| **Испытательный стенд** | Запустите пакетное тестирование комбинаций форматов, чтобы определить, какие переводы повреждены | -| **Живой монитор** | Наблюдайте за потоком запросов в режиме реального времени, чтобы выявить периодические проблемы с переводом | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Распространенные проблемы с форматами +### Common format issues -- **Теги «Мышление» не отображаются** — проверьте, поддерживает ли целевой поставщик мышление и настройку бюджета на мышление. -- **Отказ от вызовов инструментов** — Некоторые преобразования форматов могут удалять неподдерживаемые поля; проверить в режиме игровой площадки -- **Отсутствует системное приглашение** — Клод и Близнецы по-разному обрабатывают системные приглашения; проверить вывод перевода -- **SDK возвращает необработанную строку вместо объекта** — Исправлено в версии 1.1.0: средство очистки ответов теперь удаляет нестандартные поля (`x_groq`, `usage_breakdown` и т. д.), которые вызывают сбои проверки OpenAI SDK Pydantic. -- **GLM/ERNIE отклоняет роль `system`** — Исправлено в версии 1.1.0: нормализатор ролей автоматически объединяет системные сообщения с пользовательскими сообщениями для несовместимых моделей. -- **`developer` роль не распознана** — исправлено в версии 1.1.0: автоматически преобразуется в `system` для поставщиков, не поддерживающих OpenAI. -- **`json_schema` не работает с Gemini** — Исправлено в версии 1.1.0: `response_format` теперь преобразуется в `responseMimeType` Gemini + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Настройки устойчивости +## Resilience Settings -### Автоматическое ограничение скорости не срабатывает +### Auto rate-limit not triggering -- Автоматическое ограничение скорости применяется только к поставщикам ключей API (не OAuth/подписка). - – Убедитесь, что в разделе **Настройки → Устойчивость → Профили поставщиков** включено автоматическое ограничение скорости. -- Проверьте, возвращает ли поставщик коды состояния `429` или заголовки `Retry-After`. +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Настройка экспоненциальной задержки +### Tuning exponential backoff -Профили провайдеров поддерживают следующие настройки: +Provider profiles support these settings: -- **Базовая задержка** — Начальное время ожидания после первого сбоя (по умолчанию: 1 с). -- **Макс. задержка** — максимальное время ожидания (по умолчанию: 30 с). -- **Множитель** — насколько увеличить задержку за каждый последовательный сбой (по умолчанию: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -###Антигремящее стадо +### Anti-thundering herd -Когда множество одновременных запросов попадают к поставщику с ограниченной скоростью, OmniRoute использует мьютекс + автоматическое ограничение скорости для сериализации запросов и предотвращения каскадных сбоев. Это происходит автоматически для поставщиков ключей API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Все еще застрял? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Проблемы с GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Архитектура**: внутренние подробности см. в [link](ARCHITECTURE.md). -- **Справочник по API**: см. [link](API_REFERENCE.md) для всех конечных точек. -- **Панель состояния**: проверьте **Панель управления → Здоровье**, чтобы узнать состояние системы в режиме реального времени. -- **Переводчик**: используйте **Панель управления → Переводчик** для устранения проблем с форматом. +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/ru/USER_GUIDE.md b/docs/i18n/ru/USER_GUIDE.md index e17941f7c9..5a043224df 100644 --- a/docs/i18n/ru/USER_GUIDE.md +++ b/docs/i18n/ru/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Руководство пользователя +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Полное руководство по настройке поставщиков, созданию комбинаций, интеграции инструментов CLI и развертыванию OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Содержание +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 Краткий обзор цен +## 💰 Pricing at a Glance -| Уровень | Провайдер | Стоимость | Сброс квоты | Лучшее для | -| ---------------- | ------------------- | ------------------------------ | ---------------------------- | -------------------------------- | -| **💳 ПОДПИСКА** | Клод Код (Про) | 20 долларов США в месяц | 5 часов + еженедельно | Уже подписан | -| | Кодекс (Плюс/Про) | 20–200 долларов в месяц | 5 часов + еженедельно | Пользователи OpenAI | -| | Близнецы CLI | **БЕСПЛАТНО** | 180 тыс./мес + 1 тыс./день | Каждый! | -| | Второй пилот GitHub | 10–19 долларов в месяц | Ежемесячно | Пользователи GitHub | -| **🔑 КЛЮЧ API** | ДипСик | Плата за использование | Нет | Дешевое рассуждение | -| | Грок | Плата за использование | Нет | Сверхбыстрый вывод | -| | xAI (Грок) | Плата за использование | Нет | рассуждения Грока 4 | -| | Мистраль | Плата за использование | Нет | Модели, размещенные в ЕС | -| | Растерянность | Плата за использование | Нет | Расширенный поиск | -| | Вместе ИИ | Плата за использование | Нет | Модели с открытым исходным кодом | -| | Фейерверк ИИ | Плата за использование | Нет | Изображения Fast FLUX | -| | Церебра | Плата за использование | Нет | Скорость пластинчатого масштаба | -| | Согласовано | Плата за использование | Нет | Команда R+ ТРЯПКА | -| | NVIDIA НИМ | Плата за использование | Нет | Модели предприятия | -| **💰 ДЕШЕВО** | ГЛМ-4.7 | 0,6 долл. США/1 млн | Ежедневно в 10:00 | Резервное копирование бюджета | -| | МиниМакс М2.1 | 0,2 долл. США/1 млн | 5-часовой прокат | Самый дешевый вариант | -| | Кими К2 | 9 долларов в месяц за квартиру | 10 миллионов токенов в месяц | Предсказуемая стоимость | -| **🆓 БЕСПЛАТНО** | iFlow | $0 | Неограниченный | 8 моделей бесплатно | -| | Квен | $0 | Неограниченный | 3 модели бесплатно | -| | Киро | $0 | Неограниченный | Клод бесплатно | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡Совет для профессионалов:** Начните с комбинации Gemini CLI (180 000 бесплатно в месяц) + iFlow (бесплатно без ограничений) = стоимость 0 долларов США! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Варианты использования +## 🎯 Use Cases -### Случай 1: «У меня подписка Claude Pro» +### Case 1: "I have Claude Pro subscription" -**Проблема:** Срок действия квоты истекает, если она не используется, ограничения скорости во время интенсивного кодирования. +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Случай 2: «Я хочу нулевую стоимость» +### Case 2: "I want zero cost" -**Проблема:** Не могу позволить себе подписку, нужно надежное кодирование с использованием искусственного интеллекта. +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Случай 3: «Мне нужно кодирование 24/7, без перерывов» +### Case 3: "I need 24/7 coding, no interruptions" -**Проблема:** сроки, невозможность простоя +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Случай 4: «Мне нужен БЕСПЛАТНЫЙ ИИ в OpenClaw» +### Case 4: "I want FREE AI in OpenClaw" -**Проблема:** Нужен ИИ-помощник в приложениях для обмена сообщениями, совершенно бесплатно. +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Настройка провайдера +## 📖 Provider Setup -### 🔐 Поставщики подписки +### 🔐 Subscription Providers -#### Клод Код (Про/Макс) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Совет для профессионалов.** Используйте Opus для сложных задач и Sonnet для скорости. OmniRoute отслеживает квоту на каждую модель! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### Кодекс OpenAI (Плюс/Про) +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (180 000 БЕСПЛАТНО в месяц!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Лучшая цена:** Огромный уровень бесплатного пользования! Используйте это перед платными уровнями. +**Best Value:** Huge free tier! Use this before paid tiers. -#### Второй пилот GitHub +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Дешевые провайдеры +### 💰 Cheap Providers -#### GLM-4.7 (ежедневный сброс, $0,6/1 миллион) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Зарегистрируйтесь: [Zhipu AI](https://open.bigmodel.cn/) -2. Получите ключ API из плана кодирования. -3. Панель управления → Добавить ключ API: Поставщик: `glm`, Ключ API: `your-key`. +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Используйте:** `glm/glm-4.7` — **Совет для профессионалов:** План кодирования предлагает 3-кратную квоту за 1/7 стоимости! Сброс ежедневно в 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 часов сброса, 0,20 доллара США/1 миллион долларов США) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Зарегистрируйтесь: [MiniMax](https://www.minimax.io/) -2. Получите ключ API → Панель управления → Добавить ключ API. +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Используйте:** `minimax/MiniMax-M2.1` — **Совет для профессионалов:** Самый дешевый вариант для длинного контекста (1 млн токенов)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Кими К2 (фиксированная цена 9 долларов в месяц) +#### Kimi K2 ($9/month flat) -1. Подпишитесь: [Moonshot AI](https://platform.moonshot.ai/) -2. Получите ключ API → Панель управления → Добавить ключ API. +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Используйте:** `kimi/kimi-latest` — **Совет для профессионалов:** Фиксированная 9 долларов США в месяц за 10 миллионов токенов = эффективная стоимость 0,90 долларов США/1 миллион долларов США! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 БЕСПЛАТНЫЕ провайдеры +### 🆓 FREE Providers -#### iFlow (8 БЕСПЛАТНЫХ моделей) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Квен (3 БЕСПЛАТНЫЕ модели) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Киро (Клод ФРИ) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Комбо +## 🎨 Combos -### Пример 1: увеличить подписку → дешевое резервное копирование +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Пример 2: только бесплатно (нулевая стоимость) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 Интеграция CLI +## 🔧 CLI Integration -### Курсор IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Клод Код +### Claude Code -Отредактируйте `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Settings → Models → Advanced: } ``` -### Интерфейс командной строки Кодекса +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Отредактируйте `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ codex "your prompt" } ``` -**Или используйте панель инструментов:** Инструменты CLI → OpenClaw → Автонастройка. +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Клайн / Продолжить / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Развертывание +## 🚀 Deployment -### Развертывание VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### Докер +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,69 +403,72 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Для режима интеграции с хостом с двоичными файлами CLI см. раздел Docker в основной документации. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Переменные среды +### Environment Variables -| Переменная | По умолчанию | Описание | -| --------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Секрет подписания JWT (**изменение в производстве**) | -| `INITIAL_PASSWORD` | `123456` | Первый пароль для входа | -| `DATA_DIR` | `~/.omniroute` | Каталог данных (база данных, использование, журналы) | -| `PORT` | структура по умолчанию | Сервисный порт (`20128` в примерах) | -| `HOSTNAME` | структура по умолчанию | Привязать хост (по умолчанию в Docker используется `0.0.0.0`) | -| `NODE_ENV` | по умолчанию во время выполнения | Установите `production` для развертывания | -| `BASE_URL` | `http://localhost:20128` | Внутренний базовый URL-адрес на стороне сервера | -| `CLOUD_URL` | `https://omniroute.dev` | Базовый URL-адрес конечной точки облачной синхронизации | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Секрет HMAC для сгенерированных ключей API | -| `REQUIRE_API_KEY` | `false` | Принудительно использовать ключ API носителя на `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Включает журналы запросов/ответов | -| `AUTH_COOKIE_SECURE` | `false` | Принудительно использовать файл cookie аутентификации `Secure` (за обратным прокси-сервером HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Полную ссылку на переменную среды см. в [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Доступные модели +## 📊 Available Models
-Просмотреть все доступные модели +View all available models -**Код Клауда (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**Кодекс (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — БЕСПЛАТНО: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Второй пилот GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — 0,6 долларов США/1 миллион долларов США: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — 0,2 доллара США/1 миллион долларов: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — БЕСПЛАТНО: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Квен (`qw/`)** — БЕСПЛАТНО: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Киро (`kr/`)** — БЕСПЛАТНО: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` -**Грок (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` **xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**Мистраль (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Недоумение (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Вместе ИИ (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**ИИ фейерверков (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Церебра (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Согласовано (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat --- -## 🧩 Расширенные функции +## 🧩 Advanced Features -### Пользовательские модели +### Custom Models -Добавьте любой идентификатор модели к любому поставщику, не дожидаясь обновления приложения: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Или используйте панель управления: **Поставщики → [Поставщик] → Пользовательские модели**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Маршруты выделенного провайдера +### Dedicated Provider Routes -Направляйте запросы непосредственно к конкретному поставщику с проверкой модели: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Префикс провайдера добавляется автоматически, если он отсутствует. Несовпадающие модели возвращают `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Конфигурация сетевого прокси +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Приоритет:** Зависит от ключа → Зависит от комбинации → Зависит от поставщика → Глобальный → Среда. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API каталога моделей +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Возвращает модели, сгруппированные по поставщикам с типами (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Облачная синхронизация +### Cloud Sync -- Синхронизация поставщиков, комбинаций и настроек между устройствами. -- Автоматическая фоновая синхронизация с таймаутом + отказоустойчивость -- Предпочитайте серверную часть `BASE_URL`/`CLOUD_URL` в рабочей среде. +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (этап 9) +### LLM Gateway Intelligence (Phase 9) -- **Семантический кеш** — автоматически кэширует непоточные ответы с температурой = 0 (обход с помощью `X-OmniRoute-No-Cache: true`) -- **Идемпотентность запросов** — дедупликация запросов в течение 5 секунд через заголовок `Idempotency-Key` или `X-Request-Id`. -- **Отслеживание прогресса** — включите события SSE `event: progress` через заголовок `X-OmniRoute-Progress: true`. +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Игровая площадка переводчика +### Translator Playground -Доступ через **Личный кабинет → Переводчик**. Отладка и визуализация того, как OmniRoute преобразует запросы API между поставщиками. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Режим | Цель | -| ----------------------- | -------------------------------------------------------------------------------------------------- | -| **Детская площадка** | Выберите исходный/целевой формат, вставьте запрос и мгновенно просмотрите переведенный результат | -| **Тестер чата** | Отправляйте сообщения в чате через прокси и проверяйте полный цикл запросов/ответов | -| **Испытательный стенд** | Запустите пакетные тесты для нескольких комбинаций форматов, чтобы проверить правильность перевода | -| **Живой монитор** | Наблюдайте за переводами в реальном времени, пока запросы проходят через прокси | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Случаи использования:** +**Use cases:** -- Отладка причины сбоя конкретной комбинации клиента/провайдера. -- Убедитесь, что теги мышления, вызовы инструментов и системные подсказки переводятся правильно. -- Сравните различия форматов между форматами API OpenAI, Claude, Gemini и Responses. +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Стратегии маршрутизации +### Routing Strategies -Настройте через **Панель управления → Настройки → Маршрутизация**. +Configure via **Dashboard → Settings → Routing**. -| Стратегия | Описание | -| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| **Сначала заполните** | Использует учетные записи в порядке приоритета — основная учетная запись обрабатывает все запросы, пока они не станут недоступны | -| **Круговая система** | Циклически перебирает все учетные записи с настраиваемым фиксированным лимитом (по умолчанию: 3 вызова на учетную запись) | -| **P2C (Сила двух вариантов)** | Выбирает 2 случайных аккаунта и направляется к более здоровому — балансирует нагрузку с осознанием здоровья | -| **Случайный** | Случайным образом выбирает учетную запись для каждого запроса, используя перемешивание Фишера-Йейтса | -| **Наименее используемый** | Маршруты к аккаунту с самой старой меткой времени `lastUsedAt`, трафик распределяется равномерно | -| **Оптимизирована стоимость** | Маршруты к учетной записи с наименьшим значением приоритета, оптимизация для поставщиков с наименьшими затратами | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Псевдонимы модели с подстановочными знаками +#### Wildcard Model Aliases -Создайте шаблоны подстановочных знаков для переназначения имен моделей: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Подстановочные знаки поддерживают `*` (любые символы) и `?` (один символ). +Wildcards support `*` (any characters) and `?` (single character). -#### Резервные цепочки +#### Fallback Chains -Определите глобальные резервные цепочки, которые применяются ко всем запросам: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Устойчивость и автоматические выключатели +### Resilience & Circuit Breakers -Настройте через **Панель управления → Настройки → Устойчивость**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute реализует устойчивость на уровне поставщика с помощью четырех компонентов: +OmniRoute implements provider-level resilience with four components: -1. **Профили поставщиков** — конфигурация каждого поставщика для: - - Порог отказа (сколько отказов до открытия) - - Продолжительность перезарядки - - Чувствительность определения ограничения скорости - - Параметры экспоненциальной отсрочки +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Редактируемые ограничения скорости** — настройки по умолчанию на уровне системы, которые можно настроить на панели управления: - - **Запросов в минуту (RPM)** — максимальное количество запросов в минуту на аккаунт. - - **Min Time Between Requests** — Минимальный промежуток в миллисекундах между запросами. - - **Максимальное количество одновременных запросов** — максимальное количество одновременных запросов на одну учетную запись. - – Нажмите **Изменить**, чтобы изменить, затем **Сохранить** или **Отменить**. Значения сохраняются через API устойчивости. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Прерыватель цепи** — отслеживает сбои каждого провайдера и автоматически размыкает цепь при достижении порогового значения: - - **ЗАКРЫТО** (Исправно) — запросы выполняются нормально. - - **OPEN** — Провайдер временно заблокирован после повторных сбоев. - - **HALF_OPEN** — Проверка восстановления провайдера +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Политики и заблокированные идентификаторы** — отображает состояние автоматического выключателя и заблокированные идентификаторы с возможностью принудительной разблокировки. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Автоматическое определение ограничения скорости** — отслеживает заголовки `429` и `Retry-After`, чтобы заранее избежать превышения ограничений скорости провайдера. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Совет для профессионалов.** Используйте кнопку **Сбросить все**, чтобы сбросить все автоматические выключатели и время восстановления, когда поставщик услуг восстанавливается после сбоя. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Экспорт/импорт базы данных +### Database Export / Import -Управляйте резервными копиями базы данных в **Панель управления → Настройки → Система и хранилище**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Действие | Описание | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Экспорт базы данных** | Загружает текущую базу данных SQLite в виде файла `.sqlite` | -| **Экспортировать все (.tar.gz)** | Загружает полный архив резервных копий, включая: базу данных, настройки, комбинации, подключения к провайдерам (без учетных данных), метаданные ключей API | -| **Импорт базы данных** | Загрузите файл `.sqlite`, чтобы заменить текущую базу данных. Резервная копия перед импортом создается автоматически | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Проверка импорта.** Импортируемый файл проверяется на целостность (проверка прагмы SQLite), необходимые таблицы (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) и размер (максимум 100 МБ). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Примеры использования:** +**Use Cases:** -- Миграция OmniRoute между компьютерами -- Создание внешних резервных копий для аварийного восстановления. -- Делитесь конфигурациями между членами команды (экспортировать все → поделиться архивом) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Панель настроек +### Settings Dashboard -Страница настроек разделена на 5 вкладок для удобной навигации: +The settings page is organized into 5 tabs for easy navigation: -| Вкладка | Содержание | -| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Безопасность** | Настройки логина/пароля, контроль доступа по IP, аутентификация API для `/models` и блокировка провайдера | -| **Маршрутизация** | Глобальная стратегия маршрутизации (6 вариантов), псевдонимы моделей с подстановочными знаками, резервные цепочки, комбинированные значения по умолчанию | -| **Устойчивость** | Профили провайдеров, редактируемые ограничения скорости, статус автоматического выключателя, политики и заблокированные идентификаторы | -| **ИИ** | Обдумывание конфигурации бюджета, глобальная системная инъекция подсказок, статистика кэша подсказок | -| **Расширенный** | Глобальная конфигурация прокси (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Управление затратами и бюджетом +### Costs & Budget Management -Доступ через **Личный кабинет → Расходы**. +Access via **Dashboard → Costs**. -| Вкладка | Цель | -| ---------- | ------------------------------------------------------------------------------------------------------------------------- | -| **Бюджет** | Установите лимиты расходов на ключ API с ежедневными/еженедельными/месячными бюджетами и отслеживанием в реальном времени | -| **Цены** | Просмотр и редактирование записей цен модели — стоимость за 1 тыс. токенов ввода/вывода на одного поставщика | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Отслеживание затрат.** Каждый запрос регистрирует использование токенов и рассчитывает стоимость с использованием таблицы цен. Просмотрите разбивку в **Панель управления → Использование** по поставщикам, моделям и ключам API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Аудио транскрипция +### Audio Transcription -OmniRoute поддерживает транскрипцию звука через конечную точку, совместимую с OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Доступные поставщики: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Поддерживаемые аудиоформаты: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Стратегии балансировки комбо +### Combo Balancing Strategies -Настройте балансировку для каждой комбинации в **Панель управления → Комбинации → Создать/Редактировать → Стратегия**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Стратегия | Описание | -| ------------------------------ | ------------------------------------------------------------------------------------------------- | -| **Круговой** | Последовательное переключение моделей | -| **Приоритет** | Всегда пробует первую модель; возвращается только в случае ошибки | -| **Случайный** | Выбирает случайную модель из комбинации для каждого запроса | -| **Взвешенный** | Маршруты пропорциональны на основе назначенных весов для каждой модели | -| **Наименее используемый** | Маршруты к модели с наименьшим количеством недавних запросов (использует комбинированные метрики) | -| **Оптимизированная стоимость** | Маршруты к самой дешевой доступной модели (используется таблица цен) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Глобальные настройки комбо по умолчанию можно установить в **Панель управления → Настройки → Маршрутизация → Параметры комбо по умолчанию**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Панель управления здоровьем +### Health Dashboard -Доступ через **Панель управления → Здоровье**. Обзор состояния системы в реальном времени с 6 картами: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Карта | Что это показывает | -| ----------------------------- | -------------------------------------------------------------------------------------- | -| **Состояние системы** | Время работы, версия, использование памяти, каталог данных | -| **Здоровье поставщика услуг** | Состояние автоматического выключателя каждого поставщика (Закрыто/Открыто/Полуоткрыто) | -| **Ограничения ставок** | Время восстановления активного лимита скорости на аккаунт с оставшимся временем | -| **Активные блокировки** | Провайдеры временно заблокированы политикой блокировки | -| **Кэш подписей** | Статистика кэша дедупликации (активные ключи, частота попаданий) | -| **Телеметрия с задержкой** | Агрегация задержек p50/p95/p99 для каждого провайдера | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Совет для профессионалов.** Страница «Здоровье» автоматически обновляется каждые 10 секунд. Используйте карту автоматического выключателя, чтобы определить, у каких поставщиков возникли проблемы. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/sk/API_REFERENCE.md b/docs/i18n/sk/API_REFERENCE.md index 690cbed5c0..b795722c11 100644 --- a/docs/i18n/sk/API_REFERENCE.md +++ b/docs/i18n/sk/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Referencia API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Kompletná referencia pre všetky koncové body rozhrania OmniRoute API. +Complete reference for all OmniRoute API endpoints. --- -## Obsah +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Kompletná referencia pre všetky koncové body rozhrania OmniRoute API. --- -## Dokončenia četu +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Vlastné hlavičky +### Custom Headers -| Hlavička | Smer | Popis | -| ------------------------ | ------- | ------------------------------------------------------ | -| `X-OmniRoute-No-Cache` | Žiadosť | Ak chcete obísť vyrovnávaciu pamäť, nastavte na `true` | -| `X-OmniRoute-Progress` | Žiadosť | Nastaviť na `true` pre udalosti postupu | -| `Idempotency-Key` | Žiadosť | Deup kľúč (okno 5s) | -| `X-Request-Id` | Žiadosť | Alternatívny dedup kľúč | -| `X-OmniRoute-Cache` | Odpoveď | `HIT` alebo `MISS` (bez streamovania) | -| `X-OmniRoute-Idempotent` | Odpoveď | `true` v prípade deduplikácie | -| `X-OmniRoute-Progress` | Odpoveď | `enabled` ak sledovanie pokroku na | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Vloženie +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Dostupní poskytovatelia: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Generovanie obrázkov +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Dostupní poskytovatelia: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Zoznam modelov +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Koncové body kompatibility +## Compatibility Endpoints -| Metóda | Cesta | Formát | -| --------- | --------------------------- | --------------------- | -| Zverejniť | `/v1/chat/completions` | OpenAI | -| Zverejniť | `/v1/messages` | Antropický | -| Zverejniť | `/v1/responses` | Odpovede OpenAI | -| Zverejniť | `/v1/embeddings` | OpenAI | -| Zverejniť | `/v1/images/generations` | OpenAI | -| ZÍSKAJTE | `/v1/models` | OpenAI | -| Zverejniť | `/v1/messages/count_tokens` | Antropický | -| ZÍSKAJTE | `/v1beta/models` | Blíženci | -| Zverejniť | `/v1beta/models/{...path}` | Gemini generovaťObsah | -| Zverejniť | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Vyhradené trasy poskytovateľa +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Ak chýba predpona poskytovateľa, automaticky sa pridá. Nezhodné modely vrátia `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Sémantická vyrovnávacia pamäť +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Príklad odpovede: +Response example: ```json { @@ -164,152 +164,162 @@ Príklad odpovede: ## Dashboard & Management -### Autentifikácia +### Authentication -| Koncový bod | Metóda | Popis | -| ----------------------------- | --------- | --------------------------------- | -| `/api/auth/login` | Zverejniť | Prihlásiť sa | -| `/api/auth/logout` | Zverejniť | Odhlásiť sa | -| `/api/settings/require-login` | GET/PUT | Vyžaduje sa prepnutie prihlásenia | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Správa poskytovateľa +### Provider Management -| Koncový bod | Metóda | Popis | -| ---------------------------- | --------------------- | ---------------------------------- | -| `/api/providers` | ZÍSKAŤ/POSLAŤ | Zoznam / vytvorenie poskytovateľov | -| `/api/providers/[id]` | GET/PUT/DELETE | Spravovať poskytovateľa | -| `/api/providers/[id]/test` | Zverejniť | Test pripojenia poskytovateľa | -| `/api/providers/[id]/models` | ZÍSKAJTE | Zoznam modelov poskytovateľov | -| `/api/providers/validate` | Zverejniť | Overiť konfiguráciu poskytovateľa | -| `/api/provider-nodes*` | Rôzne | Správa uzla poskytovateľa | -| `/api/provider-models` | ZÍSKAŤ/POSLAŤ/VYMAZAŤ | Vlastné modely | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Toky OAuth +### OAuth Flows -| Koncový bod | Metóda | Popis | -| -------------------------------- | ------ | ---------------------------------- | -| `/api/oauth/[provider]/[action]` | Rôzne | OAuth špecifické pre poskytovateľa | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Smerovanie a konfigurácia +### Routing & Config -| Koncový bod | Metóda | Popis | -| --------------------- | ------------- | --------------------------------------- | -| `/api/models/alias` | ZÍSKAŤ/POSLAŤ | Modelové aliasy | -| `/api/models/catalog` | ZÍSKAJTE | Všetky modely podľa poskytovateľa + typ | -| `/api/combos*` | Rôzne | Kombinovaný manažment | -| `/api/keys*` | Rôzne | Správa kľúčov API | -| `/api/pricing` | ZÍSKAJTE | Cena modelu | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Použitie a analýza +### Usage & Analytics -| Koncový bod | Metóda | Popis | -| --------------------------- | -------- | ---------------------------- | -| `/api/usage/history` | ZÍSKAJTE | História používania | -| `/api/usage/logs` | ZÍSKAJTE | Denníky používania | -| `/api/usage/request-logs` | ZÍSKAJTE | Protokoly na úrovni žiadosti | -| `/api/usage/[connectionId]` | ZÍSKAJTE | Použitie na pripojenie | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Nastavenia +### Settings -| Koncový bod | Metóda | Popis | -| ------------------------------- | --------- | --------------------------------- | -| `/api/settings` | GET/PUT | Všeobecné nastavenia | -| `/api/settings/proxy` | GET/PUT | Konfigurácia sieťového proxy | -| `/api/settings/proxy/test` | Zverejniť | Test pripojenia proxy | -| `/api/settings/ip-filter` | GET/PUT | Zoznam povolených/blokovaných IP | -| `/api/settings/thinking-budget` | GET/PUT | Zdôvodnenie symbolického rozpočtu | -| `/api/settings/system-prompt` | GET/PUT | Výzva globálneho systému | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Monitorovanie +### Monitoring -| Koncový bod | Metóda | Popis | -| ------------------------ | ---------- | ---------------------------------------- | -| `/api/sessions` | ZÍSKAJTE | Sledovanie aktívnej relácie | -| `/api/rate-limits` | ZÍSKAJTE | Limity sadzieb na účet | -| `/api/monitoring/health` | ZÍSKAJTE | Zdravotná prehliadka | -| `/api/cache` | GET/DELETE | Štatistiky vyrovnávacej pamäte / vymazať | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Zálohovanie a export/import +### Backup & Export/Import -| Koncový bod | Metóda | Popis | -| --------------------------- | --------- | --------------------------------------------- | -| `/api/db-backups` | ZÍSKAJTE | Zoznam dostupných záloh | -| `/api/db-backups` | PUT | Vytvorte manuálnu zálohu | -| `/api/db-backups` | Zverejniť | Obnoviť z konkrétnej zálohy | -| `/api/db-backups/export` | ZÍSKAJTE | Stiahnuť databázu ako súbor .sqlite | -| `/api/db-backups/import` | Zverejniť | Nahrajte súbor .sqlite na nahradenie databázy | -| `/api/db-backups/exportAll` | ZÍSKAJTE | Stiahnite si úplnú zálohu ako archív .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | ### Cloud Sync -| Koncový bod | Metóda | Popis | -| ---------------------- | --------- | --------------------------------- | -| `/api/sync/cloud` | Rôzne | Operácie synchronizácie s cloudom | -| `/api/sync/initialize` | Zverejniť | Inicializovať synchronizáciu | -| `/api/cloud/*` | Rôzne | Správa cloudu | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Nástroje CLI +### CLI Tools -| Koncový bod | Metóda | Popis | -| ---------------------------------- | -------- | ------------------- | -| `/api/cli-tools/claude-settings` | ZÍSKAJTE | Claude CLI status | -| `/api/cli-tools/codex-settings` | ZÍSKAJTE | Status Codex CLI | -| `/api/cli-tools/droid-settings` | ZÍSKAJTE | Stav CLI Droid | -| `/api/cli-tools/openclaw-settings` | ZÍSKAJTE | Stav OpenClaw CLI | -| `/api/cli-tools/runtime/[toolId]` | ZÍSKAJTE | Generic CLI runtime | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Odpovede CLI zahŕňajú: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Odolnosť a limity rýchlosti +### ACP Agents -| Koncový bod | Metóda | Popis | -| ----------------------- | --------- | ------------------------------------- | -| `/api/resilience` | GET/PUT | Získať/aktualizovať profily odolnosti | -| `/api/resilience/reset` | Zverejniť | Resetujte ističe | -| `/api/rate-limits` | ZÍSKAJTE | Stav limitu sadzby na účet | -| `/api/rate-limit` | ZÍSKAJTE | Konfigurácia globálneho limitu sadzby | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | ### Evals -| Koncový bod | Metóda | Popis | -| ------------ | ------------- | -------------------------------------------------- | -| `/api/evals` | ZÍSKAŤ/POSLAŤ | Vypísať vyhodnocovacie sady / spustiť vyhodnotenie | +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -### Zásady +### Policies -| Koncový bod | Metóda | Popis | -| --------------- | --------------------- | ----------------------------- | -| `/api/policies` | ZÍSKAŤ/POSLAŤ/VYMAZAŤ | Spravovať pravidlá smerovania | +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -### Súlad +### Compliance -| Koncový bod | Metóda | Popis | -| --------------------------- | -------- | ----------------------------------- | -| `/api/compliance/audit-log` | ZÍSKAJTE | Protokol auditu súladu (posledné N) | +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### v1beta (kompatibilné s Gemini) +### v1beta (Gemini-Compatible) -| Koncový bod | Metóda | Popis | -| -------------------------- | --------- | -------------------------------------- | -| `/v1beta/models` | ZÍSKAJTE | Zoznam modelov vo formáte Gemini | -| `/v1beta/models/{...path}` | Zverejniť | Blíženci `generateContent` koncový bod | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -Tieto koncové body odzrkadľujú formát API Gemini pre klientov, ktorí očakávajú natívnu kompatibilitu Gemini SDK. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. -### Interné / systémové rozhrania API +### Internal / System APIs -| Koncový bod | Metóda | Popis | -| --------------- | --------- | ---------------------------------------------------------------- | -| `/api/init` | ZÍSKAJTE | Kontrola inicializácie aplikácie (používa sa pri prvom spustení) | -| `/api/tags` | ZÍSKAJTE | Modelové štítky kompatibilné s Ollamou (pre klientov Ollamy) | -| `/api/restart` | Zverejniť | Spustenie elegantného reštartu servera | -| `/api/shutdown` | Zverejniť | Spustiť elegantné vypnutie servera | +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | -> **Poznámka:** Tieto koncové body sú používané interne systémom alebo kvôli kompatibilite klienta Ollama. Koncoví používatelia ich zvyčajne nevolajú. +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Prepis zvuku +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Prepisujte zvukové súbory pomocou Deepgram alebo AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Žiadosť:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Odpoveď:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Podporovaní poskytovatelia:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Podporované formáty:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, \_\_12_TOKEN_1_TO +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Kompatibilita s Ollamou +## Ollama Compatibility -Pre klientov, ktorí používajú formát Ollama's API: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Žiadosti sa automaticky prekladajú medzi Ollama a internými formátmi. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetria +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Odpoveď:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Rozpočet +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Dostupnosť modelu +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Spracovanie žiadosti +## Request Processing -1. Klient odošle požiadavku na `/v1/*` -2. Volania obslužného programu trasy `handleChat`, `handleEmbedding`, `handleAudioTranscription` alebo `handleImageGeneration` -3. Model je vyriešený (priamy poskytovateľ/model alebo alias/kombo) -4. Prihlasovacie údaje vybrané z lokálnej databázy s filtrovaním dostupnosti účtu -5. Pre chat: `handleChatCore` — detekcia formátu, preklad, kontrola vyrovnávacej pamäte, kontrola idempotencie -6. Exekútor poskytovateľa odošle upstream požiadavku -7. Odpoveď preložená späť do formátu klienta (chat) alebo vrátená tak, ako je (vložené/obrázky/audio) -8. Používanie/protokolovanie zaznamenané -9. Záložný postup sa vzťahuje na chyby podľa pravidiel komba +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Odkaz na úplnú architektúru: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Autentifikácia +## Authentication -- Trasy hlavného panela (`/dashboard/*`) používajú súbor cookie `auth_token` -- Prihlásenie používa uložený hash hesla; návrat k `INITIAL_PASSWORD` -- `requireLogin` prepínateľné cez `/api/settings/require-login` -- trasy `/v1/*` voliteľne vyžadujú kľúč API nosiča, keď `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/sk/ARCHITECTURE.md b/docs/i18n/sk/ARCHITECTURE.md index b7c18db672..258d62df53 100644 --- a/docs/i18n/sk/ARCHITECTURE.md +++ b/docs/i18n/sk/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Architektúra OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Posledná aktualizácia: 2026-02-18_ +_Last updated: 2026-03-04_ -## Zhrnutie +## Executive Summary -OmniRoute je lokálna AI smerovacia brána a dashboard postavená na Next.js. -Poskytuje jeden koncový bod kompatibilný s OpenAI (`/v1/*`) a smeruje prevádzku medzi viacerých upstream poskytovateľov s prekladom, záložným, obnovovaním tokenov a sledovaním používania. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Základné schopnosti: +Core capabilities: -- OpenAI kompatibilný povrch API pre CLI/nástroje (28 poskytovateľov) -- Požiadavka / odpoveď na preklad medzi formátmi poskytovateľov -- Záložná kombinácia modelov (sekvencia viacerých modelov) - – Záložný režim na úrovni účtu (viac účtov na poskytovateľa) -- Správa pripojenia poskytovateľa s kľúčom OAuth + API -- Generovanie vkladania prostredníctvom `/v1/embeddings` (6 poskytovateľov, 9 modelov) -- Generovanie obrázkov prostredníctvom `/v1/images/generations` (4 poskytovatelia, 9 modelov) -- Myslite na analýzu značiek (`...`) pre modely uvažovania -- Dezinfekcia odozvy pre prísnu kompatibilitu OpenAI SDK -- Normalizácia rolí (vývojár→systém, systém→používateľ) pre kompatibilitu medzi poskytovateľmi -- Konverzia štruktúrovaného výstupu (json_schema → Gemini responseSchema) -- Miestna perzistencia pre poskytovateľov, kľúče, aliasy, kombá, nastavenia, ceny -- Sledovanie používania / nákladov a zaznamenávanie žiadostí -- Voliteľná cloudová synchronizácia pre synchronizáciu viacerých zariadení/stavov -- Zoznam povolených/blokovaných IP adries pre riadenie prístupu k API -- Myslenie na správu rozpočtu (priechodový/automatický/vlastný/adaptívny) -- Rýchle vstrekovanie globálneho systému -- Sledovanie relácií a snímanie odtlačkov prstov -- Rozšírené obmedzenie sadzieb na účet s profilmi špecifickými pre poskytovateľov -- Vzor ističa pre odolnosť poskytovateľa -- Ochrana stáda proti hromu s blokovaním mutex -- Cache deduplikácie požiadaviek na základe podpisu -- Doménová vrstva: dostupnosť modelu, cenové pravidlá, záložná politika, politika blokovania -- Stálosť stavu domény (vyrovnávacia pamäť SQLite pre záložné zdroje, rozpočty, blokovania, ističe) -- Modul politiky pre centralizované vyhodnocovanie požiadaviek (uzamknutie → rozpočet → záložné) -- Požiadajte o telemetriu s agregáciou latencie p50/p95/p99 -- ID korelácie (X-Request-Id) pre end-to-end sledovanie -- Protokolovanie auditu súladu s odhlásením podľa kľúča API -- Hodnotný rámec pre zabezpečenie kvality LLM -- Prístrojová doska UI Resilience so stavom ističa v reálnom čase -- Modulárni poskytovatelia OAuth (12 samostatných modulov pod `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Primárny runtime model: +Primary runtime model: -– Trasy aplikácie Next.js pod `src/app/api/*` implementujú rozhrania API hlavného panela aj rozhrania API kompatibility -– Zdieľané jadro SSE/smerovanie v `src/sse/*` + `open-sse/*` sa stará o vykonávanie poskytovateľa, preklad, streamovanie, záložné zdroje a používanie +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Rozsah a hranice +## Scope and Boundaries -### V rozsahu +### In Scope -- Runtime lokálnej brány -- Rozhrania API na správu informačných panelov -- Overenie poskytovateľa a obnovenie tokenu -- Požiadajte o preklad a streamovanie SSE -- Miestny stav + pretrvávanie používania -- Voliteľná orchestrácia synchronizácie s cloudom +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Mimo rozsah +### Out of Scope -- Implementácia cloudovej služby za `NEXT_PUBLIC_CLOUD_URL` -- Poskytovateľ SLA/riadiaca rovina mimo lokálneho procesu -- Samotné externé binárne súbory CLI (Claude CLI, Codex CLI atď.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Kontext systému na vysokej úrovni +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,152 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Základné komponenty runtime +## Core Runtime Components -## 1) API a Routing Layer (Next.js App Routes) +## 1) API and Routing Layer (Next.js App Routes) -Hlavné adresáre: +Main directories: -- `src/app/api/v1/*` a `src/app/api/v1beta/*` pre rozhrania API kompatibility -- `src/app/api/*` pre spravovanie/konfiguráciu API -- Ďalšie prepisy na `next.config.mjs` mape `/v1/*` na `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Dôležité cesty kompatibility: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` - – `src/app/api/v1/models/route.ts` – zahŕňa vlastné modely s `custom: true` -- `src/app/api/v1/embeddings/route.ts` – generovanie vkladania (6 poskytovateľov) -- `src/app/api/v1/images/generations/route.ts` — generovanie obrázkov (4+ poskytovatelia vrátane Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` – vyhradený chat pre jednotlivých poskytovateľov -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` – vyhradené vloženia podľa jednotlivých poskytovateľov -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` – vyhradené obrázky podľa jednotlivých poskytovateľov +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Manažérske domény: +Management domains: -- Autorizácia/nastavenia: `src/app/api/auth/*`, `src/app/api/settings/*` - – Poskytovatelia/pripojenia: `src/app/api/providers*` - – Uzly poskytovateľa: `src/app/api/provider-nodes*` - – Vlastné modely: `src/app/api/provider-models` (GET/POST/DELETE) -- Katalóg modelov: `src/app/api/models/catalog` (GET) -- Konfigurácia proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` - – Kľúče/aliasy/kombá/ceny: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Použitie: `src/app/api/usage/*` - – Synchronizácia/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Pomocníci nástrojov CLI: `src/app/api/cli-tools/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` - IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Rozpočet: `src/app/api/settings/thinking-budget` (GET/PUT) -- Systémová výzva: `src/app/api/settings/system-prompt` (GET/PUT) -- Relácie: `src/app/api/sessions` (GET) -- Limity sadzby: `src/app/api/rate-limits` (GET) -- Odolnosť: `src/app/api/resilience` (GET/PATCH) – profily poskytovateľa, istič, medzný stav rýchlosti -- Resetovanie odolnosti: `src/app/api/resilience/reset` (POST) - resetovanie ističov + cooldowny -- Štatistiky vyrovnávacej pamäte: `src/app/api/cache/stats` (GET/DELETE) -- Dostupnosť modelu: `src/app/api/models/availability` (GET/POST) -- Telemetria: `src/app/api/telemetry/summary` (GET) -- Rozpočet: `src/app/api/usage/budget` (GET/POST) -- Záložné reťazce: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Audit súladu: `src/app/api/compliance/audit-log` (GET) -- Hodnoty: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) - – Zásady: `src/app/api/policies` (GET/POST) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + jadro prekladu +## 2) SSE + Translation Core -Hlavné prietokové moduly: +Main flow modules: -- Vstup: `src/sse/handlers/chat.ts` -- Základná orchestrácia: `open-sse/handlers/chatCore.ts` -- Spúšťacie adaptéry poskytovateľa: `open-sse/executors/*` -- Detekcia formátu/konfigurácia poskytovateľa: `open-sse/services/provider.ts` -- Analýza/rozlíšenie modelu: `src/sse/services/model.ts`, `open-sse/services/model.ts` - – Logika záložného účtu: `open-sse/services/accountFallback.ts` -- Register prekladov: `open-sse/translator/index.ts` -- Transformácie streamu: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Extrakcia/normalizácia použitia: `open-sse/utils/usageTracking.ts` - – Analyzátor značiek Think: `open-sse/utils/thinkTagParser.ts` -- Obslužný nástroj vkladania: `open-sse/handlers/embeddings.ts` - – Register poskytovateľov vkladania: `open-sse/config/embeddingRegistry.ts` - – Obslužný program generovania obrázkov: `open-sse/handlers/imageGeneration.ts` - – Register poskytovateľa obrázkov: `open-sse/config/imageRegistry.ts` -- Dezinfekcia odozvy: `open-sse/handlers/responseSanitizer.ts` -- Normalizácia rolí: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Služby (obchodná logika): +Services (business logic): -- Výber účtu/bodovanie: `open-sse/services/accountSelector.ts` -- Kontextová správa životného cyklu: `open-sse/services/contextManager.ts` -- Vynútenie filtra IP: `open-sse/services/ipFilter.ts` - – Sledovanie relácií: `open-sse/services/sessionManager.ts` -- Žiadosť o deduplikáciu: `open-sse/services/signatureCache.ts` -- Okamžité vloženie do systému: `open-sse/services/systemPrompt.ts` -- Myslenie na správu rozpočtu: `open-sse/services/thinkingBudget.ts` -- Smerovanie modelu so zástupným znakom: `open-sse/services/wildcardRouter.ts` -- Správa limitu sadzieb: `open-sse/services/rateLimitManager.ts` -- Istič: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Moduly vrstvy domény: +Domain layer modules: -- Dostupnosť modelu: `src/lib/domain/modelAvailability.ts` -- Cenové pravidlá/rozpočty: `src/lib/domain/costRules.ts` - – Záložné pravidlá: `src/lib/domain/fallbackPolicy.ts` -- Kombinovaný prekladač: `src/lib/domain/comboResolver.ts` - – Zásady blokovania: `src/lib/domain/lockoutPolicy.ts` -- Modul politiky: `src/domain/policyEngine.ts` – centralizované uzamknutie → rozpočet → záložné hodnotenie - – Katalóg kódov chýb: `src/lib/domain/errorCodes.ts` - – ID žiadosti: `src/lib/domain/requestId.ts` - – Časový limit načítania: `src/lib/domain/fetchTimeout.ts` -- Vyžiadať telemetriu: `src/lib/domain/requestTelemetry.ts` -- Súlad/audit: `src/lib/domain/compliance/index.ts` -- Hodnotný bežec: `src/lib/domain/evalRunner.ts` -- Trvalosť stavu domény: `src/lib/db/domainState.ts` — SQLite CRUD pre záložné reťazce, rozpočty, históriu nákladov, stav uzamknutia, ističe +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Moduly poskytovateľa OAuth (12 samostatných súborov pod `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Index registra: `src/lib/oauth/providers/index.ts` - – Jednotliví poskytovatelia: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Tenký obal: `src/lib/oauth/providers.ts` – reexporty z jednotlivých modulov +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Vrstva perzistencie +## 3) Persistence Layer -Primárny stav DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- súbor: `${DATA_DIR}/db.json` (alebo `$XDG_CONFIG_HOME/omniroute/db.json`, ak je nastavený, inak `~/.omniroute/db.json`) -- entity: providerConnections, providerNodes, modelAliases, kombá, apiKeys, nastavenia, ceny, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Použitie DB: +Usage persistence: -- `src/lib/usageDb.ts` -- súbory: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- dodržiava rovnakú zásadu základného adresára ako `localDb` (`DATA_DIR`, potom `XDG_CONFIG_HOME/omniroute`, keď je nastavené) -- rozložené do zameraných podmodulov: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -DB stavu domény (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — operácie CRUD pre stav domény - – Tabuľky (vytvorené v `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, \_\_14_TOKEN -- Vzor vyrovnávacej pamäte pre zápis: mapy v pamäti sú autoritatívne za behu; mutácie sa zapisujú synchrónne do SQLite; stav sa obnoví z DB pri studenom štarte +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start ## 4) Auth + Security Surfaces -– Overenie súboru cookie informačného panela: `src/proxy.ts`, `src/app/api/auth/login/route.ts` - -- Generovanie/overenie kľúča API: `src/shared/utils/apiKey.ts` -- Tajomstvá poskytovateľa sa zachovali v `providerConnections` záznamoch -- Podpora odchádzajúceho proxy cez `open-sse/utils/proxyFetch.ts` (env vars) a `open-sse/utils/networkProxy.ts` (konfigurovateľné podľa poskytovateľa alebo globálne) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) ## 5) Cloud Sync -- Spustenie plánovača: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Pravidelná úloha: `src/shared/services/cloudSyncScheduler.ts` -- Kontrolná trasa: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Životný cyklus žiadosti (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -305,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Kombinovaný tok + záložný tok účtu +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -335,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Záložné rozhodnutia riadi `open-sse/services/accountFallback.ts` pomocou stavových kódov a heuristiky chybových správ. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Registrácia OAuth a životný cyklus obnovenia tokenu +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -367,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Obnovenie počas živej prevádzky sa vykonáva vo vnútri `open-sse/handlers/chatCore.ts` prostredníctvom spúšťača `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Životný cyklus cloudovej synchronizácie (povoliť / synchronizovať / zakázať) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -401,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Pravidelnú synchronizáciu spúšťa `CloudSyncScheduler`, keď je povolený cloud. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Dátový model a mapa úložiska +## Data Model and Storage Map ```mermaid erDiagram @@ -504,14 +504,14 @@ erDiagram } ``` -Súbory fyzického úložiska: +Physical storage files: -- hlavný stav: `${DATA_DIR}/db.json` (alebo `$XDG_CONFIG_HOME/omniroute/db.json`, keď je nastavený, inak `~/.omniroute/db.json`) -- štatistiky používania: `${DATA_DIR}/usage.json` -- riadky denníka žiadostí: `${DATA_DIR}/log.txt` -- voliteľné relácie ladenia prekladateľa/požiadavky: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Topológia nasadenia +## Deployment Topology ```mermaid flowchart LR @@ -523,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -542,242 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Mapovanie modulov (kritické rozhodnutie) +## Module Mapping (Decision-Critical) -### Moduly trasy a API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: rozhrania API pre kompatibilitu -- `src/app/api/v1/providers/[provider]/*`: vyhradené trasy podľa jednotlivých poskytovateľov (čet, vkladanie, obrázky) -- `src/app/api/providers*`: poskytovateľ CRUD, validácia, testovanie -- `src/app/api/provider-nodes*`: správa vlastných kompatibilných uzlov -- `src/app/api/provider-models`: správa vlastného modelu (CRUD) -- `src/app/api/models/catalog`: API úplného katalógu modelov (všetky typy zoskupené podľa poskytovateľa) -- `src/app/api/oauth/*`: toky OAuth/kódu zariadenia -- `src/app/api/keys*`: životný cyklus lokálneho kľúča API -- `src/app/api/models/alias`: správa aliasov -- `src/app/api/combos*`: správa náhradných kombinácií -- `src/app/api/pricing`: prepísanie cien pre výpočet nákladov -- `src/app/api/settings/proxy`: konfigurácia proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: test outbound proxy konektivity (POST) -- `src/app/api/usage/*`: použitie a protokoly API -- `src/app/api/sync/*` + `src/app/api/cloud/*`: synchronizácia s cloudom a pomocníci s orientáciou na cloud -- `src/app/api/cli-tools/*`: miestne zapisovače/kontroly konfigurácie CLI -- `src/app/api/settings/ip-filter`: zoznam povolených/blokovaných adries IP (GET/PUT) -- `src/app/api/settings/thinking-budget`: konfigurácia rozpočtu tokenu myslenia (GET/PUT) -- `src/app/api/settings/system-prompt`: výzva globálneho systému (GET/PUT) -- `src/app/api/sessions`: zoznam aktívnej relácie (GET) -- `src/app/api/rate-limits`: stav limitu sadzby na účet (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Jadro smerovania a vykonávania +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: analýza požiadaviek, spracovanie komb, slučka výberu účtu -- `open-sse/handlers/chatCore.ts`: preklad, odoslanie vykonávateľa, spracovanie opakovania/obnovenia, nastavenie streamu -- `open-sse/executors/*`: správanie siete a formátu špecifické pre poskytovateľa +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Register prekladov a konvertory formátov +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: register prekladateľov a orchestrácia - – Žiadosť prekladateľov: `open-sse/translator/request/*` -- Prekladatelia odpovedí: `open-sse/translator/response/*` -- Formátové konštanty: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Vytrvalosť +### Persistence -- `src/lib/localDb.ts`: trvalá konfigurácia/stav -- `src/lib/usageDb.ts`: história používania a priebežné protokoly požiadaviek +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Pokrytie poskytovateľa vykonávateľa (vzor stratégie) +## Provider Executor Coverage (Strategy Pattern) -Každý poskytovateľ má špecializovaný spúšťač rozširujúci `BaseExecutor` (v `open-sse/executors/base.ts`), ktorý poskytuje vytváranie URL, konštrukciu hlavičky, opakovanie s exponenciálnym stiahnutím, háky obnovenia poverení a metódu orchestrácie `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Exekútor | Poskytovatelia | Špeciálna manipulácia | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Konfigurácia dynamickej adresy URL/hlavičky podľa poskytovateľa | -| `AntigravityExecutor` | Google Antigravity | Vlastné ID projektu/relácie, Opakovať po analýze | -| `CodexExecutor` | Kódex OpenAI | Vkladá pokyny systému, vynucuje úsilie na uvažovanie | -| `CursorExecutor` | Kurzor IDE | Protokol ConnectRPC, kódovanie Protobuf, podpis požiadavky cez kontrolný súčet | -| `GithubExecutor` | GitHub Copilot | Obnovenie tokenu kopilota, hlavičky napodobňujúce VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Binárny formát AWS EventStream → Konverzia SSE | -| `GeminiCLIExecutor` | Gemini CLI | Cyklus obnovenia tokenu Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Všetci ostatní poskytovatelia (vrátane vlastných kompatibilných uzlov) používajú `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Matica kompatibility poskytovateľa +## Provider Compatibility Matrix -| Poskytovateľ | Formát | Auth | Stream | Nestreamovať | Obnovenie tokenu | Použitie API | -| ---------------- | ---------------- | ----------------------- | -------------------- | ------------ | ---------------- | ------------------- | -| Claude | claude | Kľúč API / OAuth | ✅ | ✅ | ✅ | ⚠️ Len správca | -| Blíženci | Blíženci | Kľúč API / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloudová konzola | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloudová konzola | -| Antigravitácia | antigravitácia | OAuth | ✅ | ✅ | ✅ | ✅ Plná kvóta API | -| OpenAI | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| Kódex | openai-responses | OAuth | ✅ nútený | ❌ | ✅ | ✅ Sadzobné limity | -| GitHub Copilot | openai | OAuth + token Copilot | ✅ | ✅ | ✅ | ✅ Snímky kvóty | -| Kurzor | kurzor | Vlastný kontrolný súčet | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (Stream udalostí) | ❌ | ✅ | ✅ Limity použitia | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Na požiadanie | -| iFlow | openai | OAuth (základné) | ✅ | ✅ | ✅ | ⚠️ Na požiadanie | -| OpenRouter | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | API kľúč | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| Zmätok | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| Spolu AI | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| Ohňostroje AI | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| Cerebras | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| Cohere | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Pokrytie formátu prekladu +## Format Translation Coverage -Medzi zistené zdrojové formáty patria: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Cieľové formáty zahŕňajú: +Target formats include: -- OpenAI chat/reakcie +- OpenAI chat/Responses - Claude -- Gemini/Gemini-CLI/Antigravitačná obálka +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Kurzor +- Cursor -Preklady používajú **OpenAI ako formát centra** — všetky konverzie prechádzajú cez OpenAI ako medziprodukt: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Preklady sa vyberajú dynamicky na základe tvaru zdroja a cieľového formátu poskytovateľa. +Translations are selected dynamically based on source payload shape and provider target format. -Ďalšie vrstvy spracovania v reťazci prekladu: +Additional processing layers in the translation pipeline: -– **Dezinfekcia odpovedí** – Odstráni neštandardné polia z odpovedí vo formáte OpenAI (streamovaných aj nestreamovaných), aby sa zabezpečila prísna zhoda so súpravou SDK +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -- **Normalizácia rolí** – Konvertuje `developer` → `system` pre ciele mimo OpenAI; zlučuje `system` → `user` pre modely, ktoré odmietajú systémovú rolu (GLM, ERNIE) - – **Think tagextrakcia** – analyzuje `...` bloky z obsahu do poľa `reasoning_content` - – **Štruktúrovaný výstup** – Konvertuje OpenAI `response_format.json_schema` na Gemini `responseMimeType` + `responseSchema` +## Supported API Endpoints -## Podporované koncové body API +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -| Koncový bod | Formát | Psovod | -| -------------------------------------------------- | --------------------- | ------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Správy | Rovnaký handler (automaticky detekovaný) | -| `POST /v1/responses` | Odpovede OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Zoznam modelov | Cesta API | -| `POST /v1/images/generations` | Obrázky OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Zoznam modelov | Cesta API | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Vyhradené pre každého poskytovateľa s overením modelu | -| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Vyhradené pre každého poskytovateľa s overením modelu | -| `POST /v1/providers/{provider}/images/generations` | Obrázky OpenAI | Vyhradené pre každého poskytovateľa s overením modelu | -| `POST /v1/messages/count_tokens` | Počet tokenov Claude | Cesta API | -| `GET /v1/models` | Zoznam modelov OpenAI | Cesta API (chat + vkladanie + obrázok + vlastné modely) | -| `GET /api/models/catalog` | Katalóg | Všetky modely zoskupené podľa poskytovateľa + typ | -| `POST /v1beta/models/*:streamGenerateContent` | Rodák Blíženci | Cesta API | -| `GET/PUT/DELETE /api/settings/proxy` | Konfigurácia proxy | Konfigurácia sieťového proxy | -| `POST /api/settings/proxy/test` | Pripojenie proxy | Koncový bod testu stavu proxy/konektivity | -| `GET/POST/DELETE /api/provider-models` | Vlastné modely | Správa vlastného modelu podľa poskytovateľa | +## Bypass Handler -## Obchádzka - -Obídená obsluha (`open-sse/utils/bypassHandler.ts`) zachytí známe požiadavky na „zahodenie“ od Claude CLI – zahrievacie pingy, extrakcie titulov a počty tokenov – a vráti **falošnú odpoveď** bez spotrebovania tokenov poskytovateľa upstream. Toto sa spustí iba vtedy, keď `User-Agent` obsahuje `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. ## Request Logger Pipeline -Záznamník požiadaviek (`open-sse/utils/requestLogger.ts`) poskytuje 7-stupňový kanál zaznamenávania ladenia, ktorý je predvolene vypnutý, povolený prostredníctvom `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Súbory sa zapisujú do `/logs//` pre každú reláciu požiadavky. +Files are written to `/logs//` for each request session. -## Režimy zlyhania a odolnosť +## Failure Modes and Resilience -## 1) Dostupnosť účtu/poskytovateľa +## 1) Account/Provider Availability -- Ochladenie účtu poskytovateľa pri prechodných chybách/chybách rýchlosti/autorizácie -- záložný účet pred neúspešnou žiadosťou -- záložný kombinovaný model, keď je vyčerpaná aktuálna cesta modelu/poskytovateľa +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Vypršanie platnosti tokenu +## 2) Token Expiry -- predbežná kontrola a obnovenie s opätovným pokusom pre poskytovateľov obnoviteľných zdrojov -- 401/403 zopakovanie po pokuse o obnovenie v základnej ceste +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Bezpečnosť toku +## 3) Stream Safety -- regulátor prúdu s vedomím odpojenia -- tok prekladu s vyprázdnením konca toku a spracovaním `[DONE]` -- záložný odhad použitia, keď chýbajú metadáta používania poskytovateľa +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Degradácia cloudovej synchronizácie +## 4) Cloud Sync Degradation -- Objavia sa chyby synchronizácie, ale lokálny runtime pokračuje -- plánovač má logiku schopnú opakovania, ale pravidelné vykonávanie v súčasnosti štandardne volá synchronizáciu na jeden pokus +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Integrita údajov +## 5) Data Integrity -- Migrácia/oprava tvaru DB pre chýbajúce kľúče -- poškodené ochranné prvky obnovenia JSON pre localDb a useDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Pozorovateľnosť a prevádzkové signály +## Observability and Operational Signals -Zdroje viditeľnosti pri spustení: +Runtime visibility sources: -- protokoly konzoly z `src/sse/utils/logger.ts` -- súhrny využitia na žiadosť v `usage.json` -- prihlásenie stavu textovej požiadavky `log.txt` -- voliteľné protokoly hlbokých požiadaviek/prekladov pod `logs/`, keď `ENABLE_REQUEST_LOGS=true` - – koncové body používania dashboardu (`/api/usage/*`) pre spotrebu používateľského rozhrania +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Hranice citlivé na bezpečnosť +## Security-Sensitive Boundaries -- Tajný kľúč JWT (`JWT_SECRET`) zabezpečuje overenie/podpísanie súboru cookie relácie dashboardu -- Počiatočné záložné heslo (`INITIAL_PASSWORD`, predvolené `123456`) musí byť v reálnych nasadeniach prepísané -- Tajný kľúč API HMAC (`API_KEY_SECRET`) zabezpečuje vygenerovaný formát lokálneho kľúča API -- Tajomstvá poskytovateľa (kľúče/tokeny API) sú uložené v lokálnej databáze a mali by byť chránené na úrovni súborového systému -- Koncové body cloudovej synchronizácie sa spoliehajú na sémantiku kľúča API + ID stroja +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Prostredie a Runtime Matrix +## Environment and Runtime Matrix -Premenné prostredia aktívne používané kódom: +Environment variables actively used by code: -- Aplikácia/autorizácia: `JWT_SECRET`, `INITIAL_PASSWORD` -- Úložisko: `DATA_DIR` -- Kompatibilné správanie uzla: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Voliteľné prepísanie základne úložiska (Linux/macOS, keď `DATA_DIR` nie je nastavené): `XDG_CONFIG_HOME` - – Bezpečnostné hashovanie: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Prihlásenie: `ENABLE_REQUEST_LOGS` - – Synchronizácia/cloudové URL: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` - – Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` a varianty s malými písmenami -- Príznaky funkcie SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` - – Pomocníci platformy/behu (nie konfigurácia špecifická pre aplikáciu): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Známe architektonické poznámky +## Known Architectural Notes -1. `usageDb` a `localDb` teraz zdieľajú rovnakú politiku základného adresára (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) s migráciou starších súborov. -2. `/api/v1/route.ts` vracia statický zoznam modelov a nie je hlavným zdrojom modelov, ktorý používa `/v1/models`. -3. Požiadavka zapisovača zapíše úplné hlavičky/telo, keď je povolené; považovať adresár denníka za citlivý. -4. Správanie cloudu závisí od správneho `NEXT_PUBLIC_BASE_URL` a dostupnosti koncového bodu cloudu. -5. Adresár `open-sse/` je publikovaný ako balík pracovného priestoru `@omniroute/open-sse` **npm**. Zdrojový kód ho importuje cez `@omniroute/open-sse/...` (vyriešené Next.js `transpilePackages`). Cesty k súborom v tomto dokumente stále používajú názov adresára `open-sse/` kvôli konzistencii. -6. Grafy na ovládacom paneli používajú **Recharts** (založené na SVG) na prístupné interaktívne analytické vizualizácie (stĺpcové grafy používania modelov, tabuľky rozdelenia poskytovateľov s mierou úspešnosti). -7. E2E testy používajú **Playwright** (`tests/e2e/`), prebiehajú cez `npm run test:e2e`. Testy jednotiek používajú **Node.js test runner** (`tests/unit/`), spúšťajú sa cez `npm run test:plan3`. Zdrojový kód pod `src/` je **TypeScript** (`.ts`/`.tsx`); pracovný priestor `open-sse/` zostáva JavaScriptom (`.js`). -8. Stránka s nastaveniami je usporiadaná do 5 záložiek: Zabezpečenie, Smerovanie (6 globálnych stratégií: fill-first, round-robin, p2c, náhodné, najmenej používané, nákladovo optimalizované), Resilience (upraviteľné limity sadzieb, istič, politiky), AI (rozpočet na myslenie, systémová výzva, prompt cache), Advanced (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Kontrolný zoznam overenia prevádzky +## Operational Verification Checklist -- Zostavte zo zdroja: `npm run build` -- Vytvoriť obrázok Docker: `docker build -t omniroute .` -- Spustite službu a overte: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- Základná adresa URL cieľového CLI by mala byť `http://:20128/v1`, keď `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/sk/CODEBASE_DOCUMENTATION.md b/docs/i18n/sk/CODEBASE_DOCUMENTATION.md index 55ceba3e00..303880c198 100644 --- a/docs/i18n/sk/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/sk/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — dokumentácia kódovej základne +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Komplexný sprievodca **omniroute** multi-poskytovateľa AI proxy routera pre začiatočníkov. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Čo je omniroute? +## 1. What Is omniroute? -omniroute je **proxy router**, ktorý sedí medzi klientmi AI (Claude CLI, Codex, Cursor IDE atď.) a poskytovateľmi AI (Anthropic, Google, OpenAI, AWS, GitHub atď.). Rieši jeden veľký problém: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Rôzni klienti AI hovoria rôznymi „jazykmi“ (formáty API) a rôzni poskytovatelia AI tiež očakávajú rôzne „jazyky“.** omniroute medzi nimi automaticky prekladá. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Predstavte si to ako univerzálny prekladateľ v Organizácii Spojených národov – každý delegát môže hovoriť akýmkoľvek jazykom a prekladateľ ho prevedie na akéhokoľvek iného delegáta. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Prehľad architektúry +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Základný princíp: Hub-and-Spoke Translation +### Core Principle: Hub-and-Spoke Translation -Celý preklad formátu prechádza cez **formát OpenAI ako centrum**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -To znamená, že potrebujete iba **N prekladateľov** (jeden na formát) namiesto **N²** (každý pár). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Štruktúra projektu +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Rozdelenie podľa jednotlivých modulov +## 4. Module-by-Module Breakdown ### 4.1 Config (`open-sse/config/`) -**Jediný zdroj pravdy** pre všetky konfigurácie poskytovateľov. +The **single source of truth** for all provider configuration. -| Súbor | Účel | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `constants.ts` | `PROVIDERS` objekt so základnými adresami URL, povereniami OAuth (predvolené), hlavičkami a predvolenými systémovými výzvami pre každého poskytovateľa. Definuje tiež `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` a `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Načíta externé poverenia z `data/provider-credentials.json` a zlúči ich s pevne zakódovanými predvolenými nastaveniami v `PROVIDERS`. Udržuje tajomstvá mimo kontroly zdroja pri zachovaní spätnej kompatibility. | -| `providerModels.ts` | Centrálny register modelov: mapuje aliasy poskytovateľa → ID modelov. Funkcie ako `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Systémové pokyny vložené do požiadaviek kódexu (obmedzenia úprav, pravidlá karantény, zásady schvaľovania). | -| `defaultThinkingSignature.ts` | Predvolené „mysliace“ podpisy pre modely Claude a Gemini. | -| `ollamaModels.ts` | Definícia schémy pre lokálne modely Ollama (názov, veľkosť, rodina, kvantizácia). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Tok načítania poverení +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Vykonávatelia (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Vykonávatelia zapuzdrujú **logiku špecifickú pre poskytovateľa** pomocou **Strategy Pattern**. Každý exekútor podľa potreby prepíše základné metódy. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Exekútor | Poskytovateľ | Kľúčové špecializácie | -| ---------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Abstraktný základ: vytváranie URL, hlavičky, logika opakovania, obnovenie poverení | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Obnovenie všeobecného tokenu OAuth pre štandardných poskytovateľov | -| `antigravity.ts` | Google Cloud Code | Generovanie ID projektu/relácie, záložné riešenie s viacerými adresami URL, vlastná opätovná analýza chybových hlásení ("resetovať po 2h7m23s") | -| `cursor.ts` | Kurzor IDE | **Najkomplexnejšie**: overenie kontrolného súčtu SHA-256, kódovanie požiadavky Protobuf, binárny prúd udalostí → analýza odpovede SSE | -| `codex.ts` | Kódex OpenAI | Vkladá systémové pokyny, riadi úrovne myslenia, odstraňuje nepodporované parametre | -| `gemini-cli.ts` | Google Gemini CLI | Vytvorenie vlastnej adresy URL (`streamGenerateContent`), obnovenie tokenu Google OAuth | -| `github.ts` | GitHub Copilot | Systém duálneho tokenu (GitHub OAuth + token Copilot), napodobňovanie hlavičky VSCode | -| `kiro.ts` | AWS CodeWhisperer | Binárne analyzovanie AWS EventStream, rámce udalostí AMZN, odhad tokenu | -| `index.ts` | — | Továreň: názov poskytovateľa máp → trieda vykonávateľa, s predvolenou rezervou | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 obslužné nástroje (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**orchestačná vrstva** – koordinuje preklad, vykonávanie, streamovanie a spracovanie chýb. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Súbor | Účel | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Central orchestrator** (~600 lines). Zvláda celý životný cyklus požiadavky: detekcia formátu → preklad → odoslanie vykonávateľa → odozva streamovania/nestreamovania → obnovenie tokenu → spracovanie chýb → protokolovanie používania. | -| `responsesHandler.ts` | Adaptér pre API Responses API OpenAI: konvertuje formát odpovedí → Dokončenia chatu → odosiela do `chatCore` → konvertuje SSE späť na formát odpovedí. | -| `embeddings.ts` | Obslužný program generovania vkladania: rieši model vkladania → poskytovateľ, odošle poskytovateľovi API, vracia odpoveď na vkladanie kompatibilnú s OpenAI. Podporuje 6+ poskytovateľov. | -| `imageGeneration.ts` | Obslužný program generovania obrázkov: rieši obrazový model → poskytovateľ, podporuje režimy kompatibilné s OpenAI, Gemini-image (Antigravity) a núdzový režim (Nebius). Vráti base64 alebo obrázky URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Životný cyklus žiadosti (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Služby (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Obchodná logika, ktorá podporuje manipulátory a vykonávateľov. +Business logic that supports the handlers and executors. -| Súbor | Účel | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Detekcia formátu** (`detectFormat`): analyzuje štruktúru tela požiadavky na identifikáciu formátov Claude/OpenAI/Gemini/Antigravity/Responses (zahŕňa heuristiku `max_tokens` pre Claude). Tiež: vytváranie adries URL, vytváranie hlavičiek, normalizácia konfigurácie myslenia. Podporuje dynamických poskytovateľov `openai-compatible-*` a `anthropic-compatible-*`. | -| `model.ts` | Analýza reťazca modelu (`claude/model-name` → `{provider: "claude", model: "model-name"}`), rozlíšenie alias s detekciou kolízií, dezinfekcia vstupu (odmietne prechádzanie cesty/riadiace znaky) a rozlíšenie informácií o modeli s podporou asynchrónneho získavania aliasov. | -| `accountFallback.ts` | Spracovanie limitu rýchlosti: exponenciálne stiahnutie (1s → 2s → 4s → max 2min), správa ochladzovania účtu, klasifikácia chýb (ktoré chyby spúšťajú záložné riešenie a nie). | -| `tokenRefresh.ts` | Obnovenie tokenu OAuth pre **každého poskytovateľa**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (dvojitý token OAuth + Copilot), Kiro (AWS SSO OIDC + Social Auth). Zahŕňa vyrovnávaciu pamäť na deduplikáciu sľubov počas letu a opakovanie s exponenciálnym sťahovaním. | -| `combo.ts` | **Kombinované modely**: reťazce záložných modelov. Ak model A zlyhá s chybou, ktorá je vhodná pre záložné riešenie, vyskúšajte model B, potom C atď. Vráti aktuálne stavové kódy proti prúdu. | -| `usage.ts` | Načítava údaje o kvótach/využívaní z rozhraní API poskytovateľa (kvóty GitHub Copilot, kvóty antigravitačného modelu, limity rýchlosti kódexu, rozpisy používania Kiro, nastavenia Claude). | -| `accountSelector.ts` | Inteligentný výber účtu s algoritmom hodnotenia: zohľadňuje prioritu, zdravotný stav, priebežnú pozíciu a stav chladenia, aby sa vybral optimálny účet pre každú požiadavku. | -| `contextManager.ts` | Správa životného cyklu kontextu požiadavky: vytvára a sleduje kontextové objekty pre každú požiadavku s metadátami (ID požiadavky, časové pečiatky, informácie o poskytovateľovi) na ladenie a protokolovanie. | -| `ipFilter.ts` | Riadenie prístupu na základe IP: podporuje režimy zoznamu povolených a blokovaných. Pred spracovaním požiadaviek API overí IP klienta podľa nakonfigurovaných pravidiel. | -| `sessionManager.ts` | Sledovanie relácií pomocou odtlačkov prstov klienta: sleduje aktívne relácie pomocou hashovaných identifikátorov klienta, monitoruje počet žiadostí a poskytuje metriky relácie. | -| `signatureCache.ts` | Vyrovnávacia pamäť pre deduplikáciu založenú na podpisoch: zabraňuje duplicitným požiadavkám tým, že ukladá do vyrovnávacej pamäte posledné podpisy požiadaviek a vracia odpovede uložené vo vyrovnávacej pamäti pre identické požiadavky v rámci časového okna. | -| `systemPrompt.ts` | Globálne vloženie systémovej výzvy: predpíše alebo pridá konfigurovateľnú systémovú výzvu ku všetkým požiadavkám so spracovaním kompatibility jednotlivých poskytovateľov. | -| `thinkingBudget.ts` | Správa rozpočtu tokenu uvažovania: podporuje režimy passthrough, auto (konfigurácia uvažovania v pásme), vlastné (pevný rozpočet) a adaptívne (škálované na komplexnosť) na riadenie tokenov myslenia/uvažovania. | -| `wildcardRouter.ts` | Smerovanie vzoru zástupných znakov: rozdeľuje vzory zástupných znakov (napr. `*/claude-*`) na konkrétne páry poskytovateľ/model na základe dostupnosti a priority. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Deduplikácia obnovenia tokenu +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Stav záložného účtu +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Kombinovaný modelový reťazec +#### Combo Model Chain ```mermaid flowchart LR @@ -346,9 +346,9 @@ flowchart LR ### 4.5 Translator (`open-sse/translator/`) -**Formátový prekladový nástroj** využívajúci samoregistračný systém doplnkov. +The **format translation engine** using a self-registering plugin system. -#### Architektúra +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Adresár | Súbory | Popis | -| ------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `request/` | 8 prekladateľov | Prevod tela požiadaviek medzi formátmi. Každý súbor sa pri importe sám zaregistruje prostredníctvom `register(from, to, fn)`. | -| `response/` | 7 prekladateľov | Konvertujte časti odozvy streamovania medzi formátmi. Zvláda typy udalostí SSE, bloky myslenia, volania nástrojov. | -| `helpers/` | 6 pomocníkov | Zdieľané nástroje: `claudeHelper` (extrakcia systémového promptu, konfigurácia myslenia), `geminiHelper` (mapovanie častí/obsahu), `openaiHelper` (filtrovanie formátu), `toolCallHelper` (generovanie ID ), 1 `responsesApiHelper`. | -| `index.ts` | — | Prekladový stroj: `translateRequest()`, `translateResponse()`, správa štátu, registratúra. | -| `formats.ts` | — | Formátové konštanty: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, , | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Kľúčový dizajn: Samoregistračné doplnky +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -397,17 +397,17 @@ import "./request/claude-to-openai.js"; // ← self-registers ### 4.6 Utils (`open-sse/utils/`) -| Súbor | Účel | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Vytváranie odozvy na chyby (formát kompatibilný s OpenAI), analyzovanie chýb upstream, extrakcia opakovania antigravitácie z chybových správ, streamovanie chýb SSE. | -| `stream.ts` | **SSE Transform Stream** – hlavný streamingový kanál. Dva režimy: `TRANSLATE` (preklad plného formátu) a `PASSTHROUGH` (normalizácia + extrahovanie). Rieši ukladanie kúskov do vyrovnávacej pamäte, odhad využitia, sledovanie dĺžky obsahu. Inštancie kódovača/dekodéra podľa prúdu sa vyhýbajú zdieľanému stavu. | -| `streamHelpers.ts` | Nízkoúrovňové nástroje SSE: `parseSSELine` (tolerujúce biele miesta), `hasValuableContent` (filtruje prázdne časti pre OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (sériový formát so SformatSE\_) `perf_metrics` čistenie). | -| `usageTracking.ts` | Extrakcia použitia tokenov z ľubovoľného formátu (Claude/OpenAI/Gemini/Responses), odhad so samostatnými pomermi znakov na token/nástroje/správy, pridanie do vyrovnávacej pamäte (bezpečnostná rezerva 2000 tokenov), filtrovanie polí podľa formátu, protokolovanie konzoly s farbami ANSI. | -| `requestLogger.ts` | Protokolovanie žiadostí na základe súborov (prihlásenie cez `ENABLE_REQUEST_LOGS=true`). Vytvára priečinky relácie s očíslovanými súbormi: `1_req_client.json` → `7_res_client.txt`. Všetky I/O sú asynchrónne (fire-and-forget). Maskuje citlivé hlavičky. | -| `bypassHandler.ts` | Zachytáva špecifické vzory z Claude CLI (extrakcia titulov, zahrievanie, počet) a vracia falošné odpovede bez volania akéhokoľvek poskytovateľa. Podporuje streamovanie aj nestreamovanie. Zámerne obmedzené na rozsah Claude CLI. | -| `networkProxy.ts` | Vyrieši adresu URL odchádzajúcej proxy pre daného poskytovateľa s prioritou: konfigurácia špecifická pre poskytovateľa → globálna konfigurácia → premenné prostredia (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Podporuje `NO_PROXY` vylúčenia. Konfiguráciu vyrovnávacej pamäte na 30 sekúnd. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Streamovací kanál SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Požiadať o štruktúru relácie zapisovača +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Aplikačná vrstva (`src/`) +### 4.7 Application Layer (`src/`) -| Adresár | Účel | -| ------------- | --------------------------------------------------------------------------------------------- | -| `src/app/` | Web UI, API routes, Express middleware, OAuth obslužné programy pre spätné volania | -| `src/lib/` | Prístup k databáze (`localDb.ts`, `usageDb.ts`), overenie, zdieľané | -| `src/mitm/` | Man-in-the-middle proxy nástroje na zachytenie prevádzky poskytovateľa | -| `src/models/` | Definície databázových modelov | -| `src/shared/` | Obal okolo funkcií open-sse (poskytovateľ, stream, chyba atď.) | -| `src/sse/` | Obslužné nástroje koncových bodov SSE, ktoré prepájajú knižnicu open-sse s expresnými cestami | -| `src/store/` | Správa stavu aplikácie | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Pozoruhodné trasy API +#### Notable API Routes -| Trasa | Metódy | Účel | -| --------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------- | -| `/api/provider-models` | ZÍSKAŤ/POSLAŤ/VYMAZAŤ | CRUD pre vlastné modely podľa poskytovateľa | -| `/api/models/catalog` | ZÍSKAJTE | Súhrnný katalóg všetkých modelov (chat, embedding, image, custom) zoskupený podľa poskytovateľa | -| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchická konfigurácia outbound proxy (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | Zverejniť | Overí pripojenie proxy a vráti verejnú IP/latenciu | -| `/v1/providers/[provider]/chat/completions` | Zverejniť | Vyhradené dokončenia chatu podľa poskytovateľa s overením modelu | -| `/v1/providers/[provider]/embeddings` | Zverejniť | Vyhradené vloženia podľa jednotlivých poskytovateľov s overením modelu | -| `/v1/providers/[provider]/images/generations` | Zverejniť | Vyhradené generovanie obrázkov podľa poskytovateľa s overením modelu | -| `/api/settings/ip-filter` | GET/PUT | Správa zoznamu povolených/blokovaných IP | -| `/api/settings/thinking-budget` | GET/PUT | Konfigurácia rozpočtu tokenu odôvodnenia (priechodový/automatický/vlastný/adaptívny) | -| `/api/settings/system-prompt` | GET/PUT | Globálna systémová okamžitá injekcia pre všetky požiadavky | -| `/api/sessions` | ZÍSKAJTE | Sledovanie aktívnych relácií a metriky | -| `/api/rate-limits` | ZÍSKAJTE | Stav limitu sadzby na účet | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Kľúčové dizajnové vzory +## 5. Key Design Patterns -### 5.1 Hub-and-Spoke preklad +### 5.1 Hub-and-Spoke Translation -Všetky formáty sa prekladajú cez **formát OpenAI ako centrum**. Pridanie nového poskytovateľa vyžaduje iba napísanie **jedného páru** prekladateľov (do/z OpenAI), nie N párov. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Vzor stratégie vykonávateľa +### 5.2 Executor Strategy Pattern -Každý poskytovateľ má vyhradenú triedu spúšťača, ktorá zdedí z `BaseExecutor`. Továreň v `executors/index.ts` vyberie ten správny za behu. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Systém zásuvných modulov s automatickou registráciou +### 5.3 Self-Registering Plugin System -Moduly prekladateľov sa pri importe zaregistrujú prostredníctvom `register()`. Pridanie nového prekladača je len vytvorenie súboru a jeho importovanie. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Zálohovanie účtu s exponenciálnym spätným odkladom +### 5.4 Account Fallback with Exponential Backoff -Keď poskytovateľ vráti 429/401/500, systém sa môže prepnúť na ďalší účet, pričom použije exponenciálne cooldowny (1s → 2s → 4s → max 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Kombinované modelové reťaze +### 5.5 Combo Model Chains -„Komba“ zoskupuje viacero reťazcov `provider/model`. Ak prvý zlyhá, automaticky sa vráťte k ďalšiemu. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Stavový preklad streamovania +### 5.6 Stateful Streaming Translation -Preklad odozvy udržiava stav naprieč kúskami SSE (sledovanie blokov myslenia, akumulácia volaní nástrojov, indexovanie blokov obsahu) prostredníctvom mechanizmu `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Bezpečnostná vyrovnávacia pamäť používania +### 5.7 Usage Safety Buffer -K nahlásenému použitiu je pridaná vyrovnávacia pamäť s 2000 tokenmi, aby sa klientom zabránilo naraziť na limity kontextového okna kvôli réžii systémových výziev a prekladu formátu. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Podporované formáty +## 6. Supported Formats -| Formát | Smer | Identifikátor | -| ----------------------- | ------------ | ------------------ | -| Dokončenia chatu OpenAI | zdroj + cieľ | `openai` | -| OpenAI Responses API | zdroj + cieľ | `openai-responses` | -| Antropický Claude | zdroj + cieľ | `claude` | -| Google Gemini | zdroj + cieľ | `gemini` | -| Google Gemini CLI | iba cieľ | `gemini-cli` | -| Antigravitácia | zdroj + cieľ | `antigravity` | -| AWS Kiro | iba cieľ | `kiro` | -| Kurzor | iba cieľ | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Podporovaní poskytovatelia +## 7. Supported Providers -| Poskytovateľ | Spôsob overenia | Exekútor | Kľúčové poznámky | -| ------------------------ | --------------------------------- | -------------- | -------------------------------------------------------------- | -| Antropický Claude | API kľúč alebo OAuth | Predvolené | Používa hlavičku `x-api-key` | -| Google Gemini | API kľúč alebo OAuth | Predvolené | Používa hlavičku `x-goog-api-key` | -| Google Gemini CLI | OAuth | GeminiCLI | Používa koncový bod `streamGenerateContent` | -| Antigravitácia | OAuth | Antigravitácia | Záložná ochrana viacerých adries URL, vlastná opätovná analýza | -| OpenAI | API kľúč | Predvolené | Štandardné overenie nosiča | -| Kódex | OAuth | Kódex | Vkladá systémové pokyny, riadi myslenie | -| GitHub Copilot | OAuth + token Copilot | Github | Dvojitý token, hlavička VSCode napodobňujúca | -| Kiro (AWS) | AWS SSO OIDC alebo sociálne siete | Kiro | Analýza binárneho EventStreamu | -| Kurzor IDE | Overenie kontrolného súčtu | Kurzor | Kódovanie Protobuf, kontrolné súčty SHA-256 | -| Qwen | OAuth | Predvolené | Štandardné overenie | -| iFlow | OAuth (základný + nosič) | Predvolené | Hlavička s dvojitým overením | -| OpenRouter | API kľúč | Predvolené | Štandardné overenie nosiča | -| GLM, Kimi, MiniMax | API kľúč | Predvolené | Kompatibilné s Claude, použite `x-api-key` | -| `openai-compatible-*` | API kľúč | Predvolené | Dynamický: akýkoľvek koncový bod kompatibilný s OpenAI | -| `anthropic-compatible-*` | API kľúč | Predvolené | Dynamický: akýkoľvek koncový bod kompatibilný s Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Zhrnutie toku údajov +## 8. Data Flow Summary -### Žiadosť o streamovanie +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Žiadosť o nestreamovanie +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Obtokový tok (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/sk/FEATURES.md b/docs/i18n/sk/FEATURES.md index bc9623e64d..82cc73b67b 100644 --- a/docs/i18n/sk/FEATURES.md +++ b/docs/i18n/sk/FEATURES.md @@ -1,22 +1,22 @@ -# OmniRoute — Galéria funkcií ovládacieho panela +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Vizuálny sprievodca každou sekciou ovládacieho panela OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Poskytovatelia +## 🔌 Providers -Spravujte pripojenia poskytovateľov AI: poskytovatelia OAuth (Claude Code, Codex, Gemini CLI), poskytovatelia kľúčov API (Groq, DeepSeek, OpenRouter) a bezplatní poskytovatelia (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Kombinácie +## 🎨 Combos -Vytvorte kombá smerovania modelov pomocou 6 stratégií: vyplňte ako prvé, s každým ďalším, s možnosťou dvoch možností, náhodné, najmenej používané a nákladovo optimalizované. Každé kombo spája viacero modelov s automatickým vrátením. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) @@ -24,54 +24,119 @@ Vytvorte kombá smerovania modelov pomocou 6 stratégií: vyplňte ako prvé, s ## 📊 Analytics -Komplexná analýza používania so spotrebou tokenov, odhadmi nákladov, teplotnými mapami aktivít, týždennými distribučnými grafmi a rozpismi podľa poskytovateľov. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Zdravie systému +## 🏥 System Health -Monitorovanie v reálnom čase: dostupnosť, pamäť, verzia, percentily latencie (p50/p95/p99), štatistiky vyrovnávacej pamäte a stavy ističov poskytovateľa. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Ihrisko pre prekladateľov +## 🔧 Translator Playground -Štyri režimy ladenia prekladov API: **Playground** (konvertor formátov), **Chat Tester** (živé požiadavky), **Test Bench** (dávkové testy) a **Live Monitor** (stream v reálnom čase). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Nastavenia +## 🎮 Model Playground _(v2.0.9+)_ -Všeobecné nastavenia, systémové úložisko, správa záloh (export/import databázy), vzhľad (tmavý/svetlý režim), bezpečnosť (zahŕňa ochranu koncového bodu API a blokovanie vlastného poskytovateľa), smerovanie, odolnosť a pokročilú konfiguráciu. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Nástroje CLI +## 🔧 CLI Tools -Konfigurácia nástrojov na kódovanie AI jedným kliknutím: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code a Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Vyžiadanie denníkov +## 🤖 CLI Agents _(v2.0.11+)_ -Protokolovanie požiadaviek v reálnom čase s filtrovaním podľa poskytovateľa, modelu, účtu a kľúča API. Zobrazuje stavové kódy, využitie tokenu, latenciu a podrobnosti o odozve. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Koncový bod API +## 🌐 API Endpoint -Váš zjednotený koncový bod API s rozdelením schopností: Dokončenia chatu, Vloženie, Generovanie obrázkov, Zmena poradia, Prepis zvuku a registrované kľúče API. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/sk/TROUBLESHOOTING.md b/docs/i18n/sk/TROUBLESHOOTING.md index 3f45a262fc..120092d63c 100644 --- a/docs/i18n/sk/TROUBLESHOOTING.md +++ b/docs/i18n/sk/TROUBLESHOOTING.md @@ -1,88 +1,87 @@ -# Riešenie problémov +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Bežné problémy a riešenia pre OmniRoute. +Common problems and solutions for OmniRoute. --- -## Rýchle opravy +## Quick Fixes -| Problém | Riešenie | -| ----------------------------------------------- | ----------------------------------------------------------------------- | -| Prvé prihlásenie nefunguje | Skontrolujte `INITIAL_PASSWORD` v `.env` (predvolené: `123456`) | -| Prístrojová doska sa otvára na nesprávnom porte | Nastaviť `PORT=20128` a `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Žiadne záznamy žiadostí pod `logs/` | Nastaviť `ENABLE_REQUEST_LOGS=true` | -| EACCES: povolenie zamietnuté | Nastaviť `DATA_DIR=/path/to/writable/dir` na prepísanie `~/.omniroute` | -| Stratégia smerovania sa neukladá | Aktualizácia na v1.4.11+ (Oprava schémy Zod pre pretrvávanie nastavení) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Problémy s poskytovateľom +## Provider Issues -### „Jazykový model neposkytol správy“ +### "Language model did not provide messages" -**Príčina:** Kvóta poskytovateľa je vyčerpaná. +**Cause:** Provider quota exhausted. -**Oprava:** +**Fix:** -1. Skontrolujte sledovanie kvót palubnej dosky -2. Použite kombináciu so záložnými vrstvami -3. Prejdite na lacnejšiu/bezplatnú úroveň +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Obmedzenie sadzieb +### Rate Limiting -**Príčina:** Kvóta odberov je vyčerpaná. +**Cause:** Subscription quota exhausted. -**Oprava:** +**Fix:** -– Pridať záložnú: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -- Použite GLM/MiniMax ako lacnú zálohu +### OAuth Token Expired -### Platnosť tokenu OAuth vypršala - -OmniRoute automaticky obnovuje tokeny. Ak problémy pretrvávajú: +OmniRoute auto-refreshes tokens. If issues persist: 1. Dashboard → Provider → Reconnect -2. Odstráňte a znova pridajte pripojenie poskytovateľa +2. Delete and re-add the provider connection --- -## Problémy s cloudom +## Cloud Issues -### Chyby synchronizácie cloudu +### Cloud Sync Errors -1. Overte `BASE_URL` body na vašu spustenú inštanciu (napr. `http://localhost:20128`) -2. Overte `CLOUD_URL` bodov do vášho koncového bodu cloudu (napr. `https://omniroute.dev`) -3. Ponechajte hodnoty `NEXT_PUBLIC_*` zarovnané s hodnotami na strane servera +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Vrátenie 500 +### Cloud `stream=false` Returns 500 -**Príznak:** `Unexpected token 'd'...` na koncovom bode cloudu pre hovory bez streamovania. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Príčina:** Upstream vracia užitočné zaťaženie SSE, zatiaľ čo klient očakáva JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Náhradné riešenie:** Na priame hovory v cloude použite `stream=true`. Miestne prostredie runtime zahŕňa záložnú verziu SSE→JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud hovorí Pripojené, ale „neplatný kľúč API“ +### Cloud Says Connected but "Invalid API key" -1. Vytvorte nový kľúč z miestneho informačného panela (`/api/keys`) -2. Spustite synchronizáciu s cloudom: Povoliť cloud → Synchronizovať teraz -3. Staré/nesynchronizované kľúče môžu stále vrátiť `401` v cloude +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Problémy s Dockerom +## Docker Issues -### Nástroj CLI zobrazuje, že nie je nainštalované +### CLI Tool Shows Not Installed -1. Skontrolujte polia runtime: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Pre prenosný režim: použite cieľový obrázok `runner-cli` (pribalené CLI) -3. Pre režim pripojenia hostiteľa: nastavte `CLI_EXTRA_PATHS` a pripojte adresár hostiteľského bin ako len na čítanie -4. Ak sa našli `installed=true` a `runnable=false`: binárne súbory, ale neprešli kontrolou stavu +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Rýchla prevádzková validácia +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -92,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Problémy s nákladmi +## Cost Issues -### Vysoké náklady +### High Costs -1. Skontrolujte štatistiky používania v Dashboard → Usage -2. Prepnite primárny model na GLM/MiniMax -3. Na nekritické úlohy používajte bezplatnú vrstvu (Gemini CLI, iFlow). -4. Nastavte rozpočty nákladov na kľúč API: Dashboard → API Keys → Budget +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Ladenie +## Debugging -### Povoliť protokoly požiadaviek +### Enable Request Logs -Nastavte `ENABLE_REQUEST_LOGS=true` vo svojom súbore `.env`. Protokoly sa zobrazujú v adresári `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Skontrolujte zdravie poskytovateľa +### Check Provider Health ```bash # Health dashboard @@ -121,101 +120,135 @@ curl http://localhost:20128/api/monitoring/health ### Runtime Storage -- Hlavný stav: `${DATA_DIR}/db.json` (poskytovatelia, kombá, aliasy, kľúče, nastavenia) -- Použitie: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Denníky žiadostí: `/logs/...` (keď `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Problémy s ističom +## Circuit Breaker Issues -### Poskytovateľ je zaseknutý v stave OPEN +### Provider stuck in OPEN state -Keď je istič poskytovateľa OTVORENÝ, požiadavky sú zablokované, kým nevyprší cooldown. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Oprava:** +**Fix:** -1. Prejdite na **Hlavný panel → Nastavenia → Odolnosť** -2. Skontrolujte kartu ističa príslušného poskytovateľa -3. Kliknite na **Reset All**, aby ste vymazali všetky ističe, alebo počkajte, kým uplynie cooldown -4. Pred resetovaním skontrolujte, či je poskytovateľ skutočne dostupný +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Poskytovateľ neustále vypína istič +### Provider keeps tripping the circuit breaker -Ak poskytovateľ opakovane prejde do stavu OTVORENÉ: +If a provider repeatedly enters OPEN state: -1. Vzor zlyhania nájdete v **Dashboard → Health → Provider Health** -2. Prejdite na **Nastavenia → Odolnosť → Profily poskytovateľa** a zvýšte prah zlyhania -3. Skontrolujte, či poskytovateľ zmenil limity API alebo či nevyžaduje opätovné overenie -4. Skontrolujte telemetriu latencie – vysoká latencia môže spôsobiť zlyhania súvisiace s časovým limitom +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Problémy s prepisom zvuku +## Audio Transcription Issues -### Chyba „Nepodporovaný model“. +### "Unsupported model" error -- Uistite sa, že používate správnu predponu: `deepgram/nova-3` alebo `assemblyai/best` - – Overte, či je poskytovateľ pripojený v **Dashboard → Providers** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Prepis sa vráti prázdny alebo zlyhá +### Transcription returns empty or fails -- Skontrolujte podporované zvukové formáty: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Overte, či je veľkosť súboru v rámci limitov poskytovateľa (zvyčajne < 25 MB) -- Skontrolujte platnosť kľúča API poskytovateľa na karte poskytovateľa +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Ladenie prekladača +## Translator Debugging -Na ladenie problémov s prekladom formátu použite **Dashboard → Translator**: +Use **Dashboard → Translator** to debug format translation issues: -| Režim | Kedy použiť | -| --------------------- | --------------------------------------------------------------------------------------------------------------- | -| **Ihrisko** | Porovnajte vstupné/výstupné formáty vedľa seba — prilepte neúspešnú požiadavku, aby ste videli, ako sa prekladá | -| **Tester chatu** | Posielajte živé správy a skontrolujte celý obsah žiadosti/odpovede vrátane hlavičiek | -| **Testovacia lavica** | Spustite dávkové testy kombinácií formátov, aby ste zistili, ktoré preklady sú poškodené | -| **Živý monitor** | Sledujte tok žiadostí v reálnom čase, aby ste zachytili občasné problémy s prekladom | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Bežné problémy s formátom +### Common format issues -- **Značky myslenia sa nezobrazujú** — Skontrolujte, či cieľový poskytovateľ podporuje myslenie a nastavenie rozpočtu na myslenie -- **Volania nástrojov klesajú** – Niektoré preklady formátov môžu odstrániť nepodporované polia; overiť v režime Playground -- **Chýba systémová výzva** – Claude a Gemini riešia výzvy systému odlišne; skontrolujte výstup prekladu - – **SDK vracia nespracovaný reťazec namiesto objektu** – Opravené vo verzii 1.1.0: nástroj na dezinfekciu odpovede teraz odstraňuje neštandardné polia (`x_groq`, `usage_breakdown` atď.), ktoré spôsobujú zlyhania overenia OpenAI SDK Pydantic -- **GLM/ERNIE odmieta rolu `system`** — Opravené vo verzii 1.1.0: normalizátor rolí automaticky zlučuje systémové správy do používateľských správ pre nekompatibilné modely - – **`developer` rola nebola rozpoznaná** – Opravené vo verzii 1.1.0: automaticky konvertované na `system` pre poskytovateľov, ktorí nie sú OpenAI - – **`json_schema` nefunguje s Gemini** – Opravené vo verzii 1.1.0: `response_format` je teraz prevedené na `responseMimeType` + `responseSchema` Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Nastavenia odolnosti +## Resilience Settings -### Automatický limit rýchlosti sa nespustí +### Auto rate-limit not triggering -- Automatický limit sadzby sa vzťahuje len na poskytovateľov kľúčov API (nie OAuth/predplatné) -- Skontrolujte, či je v **Nastaveniach → Odolnosť → Profily poskytovateľov** povolený automatický limit rýchlosti - – Skontrolujte, či poskytovateľ vracia `429` stavové kódy alebo hlavičky `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Ladenie exponenciálneho ústupu +### Tuning exponential backoff -Profily poskytovateľov podporujú tieto nastavenia: +Provider profiles support these settings: -- **Základné oneskorenie** — Počiatočná doba čakania po prvom zlyhaní (predvolené: 1 s) - – **Maximálne oneskorenie** – Obmedzenie maximálnej doby čakania (predvolené: 30 s) -- **Násobiteľ** – o koľko sa má predĺžiť oneskorenie pri následnom zlyhaní (predvolené: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Protihromové stádo +### Anti-thundering herd -Keď mnoho súbežných požiadaviek zasiahne poskytovateľa s obmedzenou rýchlosťou, OmniRoute použije mutex + automatické obmedzenie rýchlosti na serializáciu požiadaviek a zabránenie kaskádovým zlyhaniam. Toto je automatické pre poskytovateľov kľúčov API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Stále ste uviazli? +## Optional RAG / LLM failure taxonomy (16 problems) -– **Problémy s GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. -- **Architektúra**: Interné podrobnosti nájdete v [link](ARCHITECTURE.md) -- **Referencia API**: Všetky koncové body nájdete na stránke [link](API_REFERENCE.md) -- **Hlavný panel zdravia**: Skontrolujte stav systému v reálnom čase v časti **Hlavný panel → Zdravie** -- **Prekladač**: Na ladenie problémov s formátom použite **Dashboard → Translator** +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/sk/USER_GUIDE.md b/docs/i18n/sk/USER_GUIDE.md index 01a351e8bc..5a043224df 100644 --- a/docs/i18n/sk/USER_GUIDE.md +++ b/docs/i18n/sk/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Používateľská príručka +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Kompletný sprievodca pre konfiguráciu poskytovateľov, vytváranie komb, integráciu nástrojov CLI a nasadenie OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Obsah +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Kompletný sprievodca pre konfiguráciu poskytovateľov, vytváranie komb, integ --- -## 💰 Prehľad cien +## 💰 Pricing at a Glance -| Úroveň | Poskytovateľ | Náklady | Obnovenie kvóty | Najlepšie pre | -| ----------------- | ----------------- | ------------------- | ---------------------------- | --------------------------- | -| **💳 PREDPLATNÉ** | Claude Code (Pro) | 20 USD/mesiac | 5h + týždenne | Už prihlásené | -| | Codex (Plus/Pro) | 20 – 200 USD/mesiac | 5h + týždenne | Používatelia OpenAI | -| | Gemini CLI | **ZADARMO** | 180 tis./mesiac + 1 tis./deň | Všetci! | -| | GitHub Copilot | 10 – 19 USD/mes. | Mesačne | Používatelia GitHubu | -| **🔑 API KEY** | DeepSeek | Platba za použitie | Žiadne | Lacné uvažovanie | -| | Groq | Platba za použitie | Žiadne | Ultra-rýchle odvodenie | -| | xAI (Grok) | Platba za použitie | Žiadne | Grok 4 zdôvodnenie | -| | Mistral | Platba za použitie | Žiadne | Modely hostené v EÚ | -| | Zmätok | Platba za použitie | Žiadne | Rozšírené vyhľadávanie | -| | Spolu AI | Platba za použitie | Žiadne | Modely s otvoreným zdrojom | -| | Ohňostroje AI | Platba za použitie | Žiadne | Fast FLUX obrázky | -| | Cerebras | Platba za použitie | Žiadne | Rýchlosť plátkovej stupnice | -| | Cohere | Platba za použitie | Žiadne | Príkaz R+ RAG | -| | NVIDIA NIM | Platba za použitie | Žiadne | Podnikové modely | -| **💰 LACNO** | GLM-4,7 | 0,6 USD/1 milión | Denne 10:00 | Záloha rozpočtu | -| | MiniMax M2.1 | 0,2 USD/1 milión | 5-hodinové valcovanie | Najlacnejšia možnosť | -| | Kimi K2 | 9 USD/mesiac byt | 10 miliónov tokenov/mesiac | Predvídateľné náklady | -| **🆓 ZDARMA** | iFlow | 0 USD | Neobmedzené | 8 modelov zadarmo | -| | Qwen | 0 USD | Neobmedzené | 3 modely zadarmo | -| | Kiro | 0 USD | Neobmedzené | Claude zadarmo | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Tip pre profesionálov:** Začnite s kombináciou Gemini CLI (180 000 zadarmo/mesiac) + iFlow (neobmedzene zadarmo) = cena 0 $! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Prípady použitia +## 🎯 Use Cases -### Prípad 1: „Mám predplatné Claude Pro“ +### Case 1: "I have Claude Pro subscription" -**Problém:** Platnosť kvóty vyprší nevyužitá, obmedzenia sadzieb počas náročného kódovania +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Prípad 2: „Chcem nulové náklady“ +### Case 2: "I want zero cost" -**Problém:** Nemôžem si dovoliť predplatné, potrebujem spoľahlivé kódovanie AI +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Prípad 3: „Potrebujem kódovanie 24/7, žiadne prerušenia“ +### Case 3: "I need 24/7 coding, no interruptions" -**Problém:** Termíny, nemôžem si dovoliť prestoje +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Prípad 4: „Chcem AI ZDARMA v OpenClaw“ +### Case 4: "I want FREE AI in OpenClaw" -**Problém:** Potrebujete asistenta AI v aplikáciách na odosielanie správ, úplne zadarmo +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Nastavenie poskytovateľa +## 📖 Provider Setup -### 🔐 Poskytovatelia predplatného +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Tip pre profesionálov:** Používajte Opus na zložité úlohy, Sonnet na rýchlosť. OmniRoute sleduje kvótu na model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (ZADARMO 180 000/mesiac!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,7 +152,7 @@ Models: gc/gemini-2.5-pro ``` -**Najlepšia hodnota:** Obrovská bezplatná úroveň! Použite to pred platenými úrovňami. +**Best Value:** Huge free tier! Use this before paid tiers. #### GitHub Copilot @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Lacní poskytovatelia +### 💰 Cheap Providers -#### GLM-4,7 (denný reset, 0,6 $/1 milión) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Zaregistrujte sa: [Zhipu AI](https://open.bigmodel.cn/) -2. Získajte kľúč API z plánu kódovania -3. Dashboard → Pridať kľúč API: Poskytovateľ: `glm`, kľúč API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Použite:** `glm/glm-4.7` — **Tip pre profesionálov:** Kódovací plán ponúka 3× kvótu za 1/7 cenu! Resetovať denne o 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. #### MiniMax M2.1 (5h reset, $0.20/1M) -1. Zaregistrujte sa: [MiniMax](https://www.minimax.io/) -2. Získať kľúč API → Dashboard → Pridať kľúč API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Použitie:** `minimax/MiniMax-M2.1` — **Tip pre profesionálov:** Najlacnejšia možnosť pre dlhý kontext (1 milión tokenov)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 (9 USD/mesiac) +#### Kimi K2 ($9/month flat) -1. Prihlásiť sa na odber: [Moonshot AI](https://platform.moonshot.ai/) -2. Získať kľúč API → Dashboard → Pridať kľúč API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Použitie:** `kimi/kimi-latest` — **Tip pre profesionálov:** Pevné 9 $/mesiac za 10 miliónov tokenov = 0,90 $/1 milión efektívnych nákladov! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 BEZPLATNÍ poskytovatelia +### 🆓 FREE Providers -#### iFlow (8 modelov ZDARMA) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 modely ZDARMA) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Kombinácie +## 🎨 Combos -### Príklad 1: Maximalizujte predplatné → Lacné zálohovanie +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Príklad 2: Iba zadarmo (nulové náklady) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 Integrácia CLI +## 🔧 CLI Integration -### IDE kurzora +### Cursor IDE ``` Settings → Models → Advanced: @@ -262,7 +262,7 @@ Settings → Models → Advanced: ### Claude Code -Upraviť `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -271,7 +271,7 @@ Upraviť `~/.claude/config.json`: } ``` -### Kódex CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Upraviť `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Upraviť `~/.openclaw/openclaw.json`: } ``` -**Alebo použite Dashboard:** Nástroje CLI → OpenClaw → Automatická konfigurácia +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Pokračovať / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Nasadenie +## 🚀 Deployment -### Nasadenie VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Informácie o režime integrovanom s hostiteľom s binárnymi súbormi CLI nájdete v časti Docker v hlavných dokumentoch. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Premenné prostredia +### Environment Variables -| Premenná | Predvolené | Popis | -| --------------------- | ------------------------------------ | ----------------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Tajomstvo podpisu JWT (**zmena vo výrobe**) | -| `INITIAL_PASSWORD` | `123456` | Prvé prihlasovacie heslo | -| `DATA_DIR` | `~/.omniroute` | Adresár údajov (db, využitie, protokoly) | -| `PORT` | štandardný rámec | Servisný port (v príkladoch `20128`) | -| `HOSTNAME` | štandardný rámec | Bind host (Docker predvolene `0.0.0.0`) | -| `NODE_ENV` | runtime default | Nastaviť `production` na nasadenie | -| `BASE_URL` | `http://localhost:20128` | Interná základná adresa URL na strane servera | -| `CLOUD_URL` | `https://omniroute.dev` | Základná adresa URL koncového bodu synchronizácie v cloude | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Tajný kľúč HMAC pre vygenerované kľúče API | -| `REQUIRE_API_KEY` | `false` | Vynútiť kľúč rozhrania Bearer API na `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Povolí protokoly požiadaviek/odpovedí | -| `AUTH_COOKIE_SECURE` | `false` | Vynútiť `Secure` autorizačný súbor cookie (za HTTPS reverzným proxy serverom) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Úplnú referenciu premenných prostredia nájdete v [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Dostupné modely +## 📊 Available Models
-Zobraziť všetky dostupné modely +View all available models **Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — ZDARMA: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** – 0,6 USD/1 milión: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** – 0,2 USD/1 milión: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — ZDARMA: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** – ZDARMA: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** – ZDARMA: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,11 +460,11 @@ Informácie o režime integrovanom s hostiteľom s binárnymi súbormi CLI nájd **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Zmätok (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` **Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Umelá inteligencia ohňostrojov (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` **Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` @@ -417,11 +476,11 @@ Informácie o režime integrovanom s hostiteľom s binárnymi súbormi CLI nájd --- -## 🧩 Pokročilé funkcie +## 🧩 Advanced Features -### Vlastné modely +### Custom Models -Pridajte akékoľvek ID modelu k akémukoľvek poskytovateľovi bez čakania na aktualizáciu aplikácie: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Alebo použite Dashboard: **Poskytovatelia → [Poskytovateľ] → Vlastné modely**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Vyhradené trasy poskytovateľa +### Dedicated Provider Routes -Smerujte požiadavky priamo ku konkrétnemu poskytovateľovi s overením modelu: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Ak chýba predpona poskytovateľa, automaticky sa pridá. Nezhodné modely vrátia `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Konfigurácia sieťového proxy +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Prednosť:** Špecifické pre kľúč → Špecifické pre kombináciu → Špecifické pre poskytovateľa → Globálne → Prostredie. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API katalógu modelov +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Vráti modely zoskupené podľa poskytovateľa s typmi (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). ### Cloud Sync -- Synchronizujte poskytovateľov, kombinácie a nastavenia medzi zariadeniami -- Automatická synchronizácia na pozadí s časovým limitom + rýchle zlyhanie -- Vo výrobe uprednostňujete `BASE_URL`/`CLOUD_URL` na strane servera +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (9. fáza) +### LLM Gateway Intelligence (Phase 9) -- **Sémantická vyrovnávacia pamäť** – Automatické ukladanie do vyrovnávacej pamäte bez streamovania, teplota = 0 odoziev (obíďte pomocou `X-OmniRoute-No-Cache: true`) - – **Idempotencia žiadosti** – Deduplikuje žiadosti do 5 s prostredníctvom hlavičky `Idempotency-Key` alebo `X-Request-Id` - – **Sledovanie pokroku** – Prihláste sa do udalostí SSE `event: progress` prostredníctvom hlavičky `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Ihrisko pre prekladateľov +### Translator Playground -Prístup cez **Dashboard → Translator**. Laďte a vizualizujte, ako OmniRoute prekladá požiadavky API medzi poskytovateľmi. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Režim | Účel | -| --------------------- | ------------------------------------------------------------------------------------------ | -| **Ihrisko** | Vyberte zdrojové/cieľové formáty, vložte požiadavku a okamžite si pozrite preložený výstup | -| **Tester chatu** | Posielajte správy živého chatu cez proxy a skontrolujte celý cyklus žiadostí/odpovedí | -| **Testovacia lavica** | Spustite dávkové testy vo viacerých kombináciách formátov na overenie správnosti prekladu | -| **Živý monitor** | Sledujte preklady v reálnom čase, keď požiadavky prechádzajú cez server proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Prípady použitia:** +**Use cases:** -- Odlaďte, prečo konkrétna kombinácia klient/poskytovateľ zlyhá -- Overte, či sa značky myslenia, volania nástrojov a systémové výzvy prekladajú správne -- Porovnajte rozdiely medzi formátmi OpenAI, Claude, Gemini a Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Stratégie smerovania +### Routing Strategies -Konfigurujte cez **Dashboard → Nastavenia → Smerovanie**. +Configure via **Dashboard → Settings → Routing**. -| Stratégia | Popis | -| ----------------------------- | ------------------------------------------------------------------------------------------------------ | -| **Vyplňte ako prvé** | Používa účty v poradí podľa priority – primárny účet spracováva všetky požiadavky, kým nie je dostupný | -| **Round Robin** | Prechádza cez všetky účty s konfigurovateľným fixným limitom (predvolené: 3 hovory na účet) | -| **P2C (sila dvoch možností)** | Vyberie 2 náhodné účty a cesty k zdravšiemu — vyrovnáva záťaž s uvedomením si zdravia | -| **Náhodné** | Náhodne vyberie účet pre každú požiadavku pomocou Fisher-Yates shuffle | -| **Najmenej používané** | Smeruje na účet s najstaršou časovou pečiatkou `lastUsedAt`, rovnomerne rozdeľuje návštevnosť | -| **Costovo optimalizované** | Smeruje na účet s najnižšou prioritou, optimalizácia pre poskytovateľov s najnižšou cenou | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Aliasy modelu so zástupnými znakmi +#### Wildcard Model Aliases -Vytvorte vzory zástupných znakov na premapovanie názvov modelov: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Zástupné znaky podporujú `*` (ľubovoľné znaky) a `?` (jeden znak). +Wildcards support `*` (any characters) and `?` (single character). -#### Záložné reťazce +#### Fallback Chains -Definujte globálne záložné reťazce, ktoré platia pre všetky požiadavky: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Odolnosť a ističe +### Resilience & Circuit Breakers -Konfigurujte cez **Dashboard → Nastavenia → Odolnosť**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementuje odolnosť na úrovni poskytovateľa so štyrmi komponentmi: +OmniRoute implements provider-level resilience with four components: -1. **Profily poskytovateľa** — Konfigurácia podľa jednotlivých poskytovateľov pre: - - Prah zlyhania (koľko porúch pred otvorením) - - Trvanie chladenia - - Citlivosť detekcie limitu rýchlosti - - Exponenciálne parametre backoff +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Upraviteľné limity rýchlosti** — Predvolené nastavenia na úrovni systému konfigurovateľné na paneli: - - **Požiadavky za minútu (RPM)** – Maximálny počet žiadostí za minútu na účet - - **Min Time Between Requests** – Minimálna medzera v milisekundách medzi požiadavkami - - **Max Concurrent Requests** – Maximálny počet simultánnych požiadaviek na účet - - Kliknite na **Upraviť** a upravte, potom na **Uložiť** alebo **Zrušiť**. Hodnoty pretrvávajú prostredníctvom rozhrania API odolnosti. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** – Sleduje zlyhania podľa poskytovateľa a automaticky otvára okruh, keď sa dosiahne prah: - - **ZATVORENÉ** (zdravé) – požiadavky prebiehajú normálne - - **OPEN** — Poskytovateľ je po opakovaných zlyhaniach dočasne zablokovaný - - **HALF_OPEN** – Testuje sa, či sa poskytovateľ zotavil +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Policies & Locked Identifiers** – Zobrazuje stav ističa a uzamknuté identifikátory s možnosťou vynútenia odomknutia. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Automatická detekcia limitu sadzby** — Monitoruje hlavičky `429` a `Retry-After`, aby sa proaktívne vyhlo prekročeniu limitov sadzby poskytovateľa. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Tip pre profesionálov:** Pomocou tlačidla **Resetovať všetko** vymažte všetky ističe a chladenia, keď sa poskytovateľ zotaví z výpadku. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Export/Import databázy +### Database Export / Import -Spravujte zálohy databázy v **Dashboard → Nastavenia → Systém a úložisko**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Akcia | Popis | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| **Exportovať databázu** | Stiahne aktuálnu databázu SQLite ako súbor `.sqlite` | -| **Exportovať všetko (.tar.gz)** | Stiahne celý záložný archív vrátane: databázy, nastavení, kombinácií, pripojení poskytovateľa (bez poverení), metadát kľúča API | -| **Importovať databázu** | Ak chcete nahradiť aktuálnu databázu, nahrajte súbor `.sqlite`. Automaticky sa vytvorí záloha pred importom | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Overenie importu:** Overí sa integrita importovaného súboru (kontrola SQLite pragma), požadované tabuľky (`provider_connections`, `provider_nodes`, `combos`, ) a veľkosť (max. 0 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Prípady použitia:** +**Use Cases:** -- Migrujte OmniRoute medzi strojmi -- Vytvorte externé zálohy na obnovu po havárii -- Zdieľanie konfigurácií medzi členmi tímu (exportovať všetko → zdieľať archív) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Panel nastavení +### Settings Dashboard -Stránka nastavení je usporiadaná do 5 kariet pre jednoduchú navigáciu: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Obsah | -| -------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| **Bezpečnosť** | Nastavenia prihlasovacieho mena/hesla, riadenie prístupu IP, overenie API pre `/models` a blokovanie poskytovateľa | -| **Smerovanie** | Globálna stratégia smerovania (6 možností), aliasy modelu so zástupnými znakmi, záložné reťazce, predvolené nastavenia komba | -| **Odolnosť** | Profily poskytovateľov, upraviteľné limity sadzieb, stav ističa, zásady a zamknuté identifikátory | -| **AI** | Konfigurácia rozpočtu myslenia, rýchle vloženie globálneho systému, rýchle štatistiky vyrovnávacej pamäte | -| **Pokročilé** | Globálna konfigurácia proxy (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Správa nákladov a rozpočtu +### Costs & Budget Management -Prístup cez **Dashboard → Náklady**. +Access via **Dashboard → Costs**. -| Tab | Účel | -| ------------ | ---------------------------------------------------------------------------------------------------------- | -| **Rozpočet** | Nastavte limity výdavkov na kľúč API s dennými/týždennými/mesačnými rozpočtami a sledovaním v reálnom čase | -| **Ceny** | Zobrazenie a úprava položiek cien modelu – cena za 1 000 vstupných/výstupných tokenov na poskytovateľa | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Sledovanie nákladov:** Každá požiadavka zaznamenáva používanie tokenu a vypočítava náklady pomocou cenovej tabuľky. Pozrite si rozpisy v **Dashboard → Použitie** podľa poskytovateľa, modelu a kľúča API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Zvukový prepis +### Audio Transcription -OmniRoute podporuje prepis zvuku cez koncový bod kompatibilný s OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Dostupní poskytovatelia: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Podporované zvukové formáty: `mp3`, `wav`, `m4a`, `flac`, `ogg`, +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Kombinované stratégie vyvažovania +### Combo Balancing Strategies -Nakonfigurujte vyváženie jednotlivých kombinácií v **Dashboard → Combos → Create/Edit → Strategy**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Stratégia | Popis | -| ---------------------------- | --------------------------------------------------------------------------------------- | -| **Round-Robin** | Postupne rotuje medzi modelmi | -| **Priorita** | Vždy vyskúšajte prvý model; vracia sa len pri chybe | -| **Náhodné** | Vyberie náhodný model z kombinácie pre každú požiadavku | -| **Vážený** | Trasy proporcionálne na základe pridelených hmotností na model | -| **Najmenej používané** | Smeruje k modelu s najmenším počtom nedávnych požiadaviek (používa kombinovanú metriku) | -| **Nákladovo optimalizované** | Trasy k najlacnejšiemu dostupnému modelu (používa cenovú tabuľku) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Globálne predvolené nastavenia pre kombináciu je možné nastaviť v **Dashboard → Settings → Routing → Combo Defaults**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Informačný panel zdravia +### Health Dashboard -Prístup cez **Dashboard → Health**. Prehľad stavu systému v reálnom čase so 6 kartami: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Karta | Čo ukazuje | -| ------------------------------- | ---------------------------------------------------------------------------- | -| **Stav systému** | Uptime, verzia, využitie pamäte, dátový adresár | -| **Zdravie poskytovateľa** | Stav ističa podľa poskytovateľa (zatvorené/otvorené/polootvorené) | -| **Obmedzenia sadzieb** | Aktívne zníženia rýchlosti limitu na účet so zostávajúcim časom | -| **Aktívne blokovania** | Poskytovatelia dočasne zablokovaní politikou uzamknutia | -| **Vyrovnávacia pamäť podpisov** | Štatistiky vyrovnávacej pamäte deduplikácie (aktívne kľúče, počet prístupov) | -| **Telemetria latencie** | p50/p95/p99 agregácia latencie podľa poskytovateľa | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Tip pre profesionálov:** Stránka Zdravie sa automaticky obnovuje každých 10 sekúnd. Pomocou karty ističa identifikujte, ktorí poskytovatelia majú problémy. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/sv/API_REFERENCE.md b/docs/i18n/sv/API_REFERENCE.md index bda0208fb0..b795722c11 100644 --- a/docs/i18n/sv/API_REFERENCE.md +++ b/docs/i18n/sv/API_REFERENCE.md @@ -1,12 +1,12 @@ -# API-referens +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Fullständig referens för alla OmniRoute API-slutpunkter. +Complete reference for all OmniRoute API endpoints. --- -## Innehållsförteckning +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Fullständig referens för alla OmniRoute API-slutpunkter. --- -## Chattavslut +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Anpassade rubriker +### Custom Headers -| Rubrik | Riktning | Beskrivning | -| ------------------------ | -------- | ----------------------------------------- | -| `X-OmniRoute-No-Cache` | Begäran | Ställ in på `true` för att kringgå cache | -| `X-OmniRoute-Progress` | Begäran | Ställ in på `true` för framstegshändelser | -| `Idempotency-Key` | Begäran | Dedup-nyckel (5s fönster) | -| `X-Request-Id` | Begäran | Alternativ dedup-nyckel | -| `X-OmniRoute-Cache` | Svar | `HIT` eller `MISS` (icke-streaming) | -| `X-OmniRoute-Idempotent` | Svar | `true` om deduplicerad | -| `X-OmniRoute-Progress` | Svar | `enabled` om förloppsspårning på | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Inbäddningar +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Tillgängliga leverantörer: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Bildgenerering +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Tillgängliga leverantörer: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Lista modeller +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Kompatibilitetsslutpunkter +## Compatibility Endpoints -| Metod | Väg | Format | -| ----- | --------------------------- | ------------------------ | -| POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Antropisk | -| POST | `/v1/responses` | OpenAI-svar | -| POST | `/v1/embeddings` | OpenAI | -| POST | `/v1/images/generations` | OpenAI | -| FÅ | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Antropisk | -| FÅ | `/v1beta/models` | Tvillingarna | -| POST | `/v1beta/models/{...path}` | Gemini generera innehåll | -| POST | `/v1/api/chat` | Ollama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Dedikerade leverantörsrutter +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Providerprefixet läggs till automatiskt om det saknas. Omatchade modeller returnerar `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Semantisk cache +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Exempel på svar: +Response example: ```json { @@ -164,152 +164,162 @@ Exempel på svar: ## Dashboard & Management -### Autentisering +### Authentication -| Slutpunkt | Metod | Beskrivning | -| ----------------------------- | ------- | ---------------------- | -| `/api/auth/login` | POST | Logga in | -| `/api/auth/logout` | POST | Logga ut | -| `/api/settings/require-login` | GET/PUT | Växla inloggning krävs | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Leverantörshantering +### Provider Management -| Slutpunkt | Metod | Beskrivning | -| ---------------------------- | ---------------- | ------------------------------------ | -| `/api/providers` | GET/POSTA | Lista / skapa leverantörer | -| `/api/providers/[id]` | GET/PUT/DELETE | Hantera en leverantör | -| `/api/providers/[id]/test` | POST | Testa leverantörsanslutning | -| `/api/providers/[id]/models` | FÅ | Lista leverantörsmodeller | -| `/api/providers/validate` | POST | Validera leverantörens konfiguration | -| `/api/provider-nodes*` | Olika | Leverantörsnodhantering | -| `/api/provider-models` | GET/POSTA/RADERA | Anpassade modeller | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth-flöden +### OAuth Flows -| Slutpunkt | Metod | Beskrivning | -| -------------------------------- | ----- | ------------------------- | -| `/api/oauth/[provider]/[action]` | Olika | Leverantörsspecifik OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | ### Routing & Config -| Slutpunkt | Metod | Beskrivning | -| --------------------- | --------- | ------------------------------------ | -| `/api/models/alias` | GET/POSTA | Modellalias | -| `/api/models/catalog` | FÅ | Alla modeller efter leverantör + typ | -| `/api/combos*` | Olika | Kombinationshantering | -| `/api/keys*` | Olika | API-nyckelhantering | -| `/api/pricing` | FÅ | Modellprissättning | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Användning och analys +### Usage & Analytics -| Slutpunkt | Metod | Beskrivning | -| --------------------------- | ----- | ------------------------- | -| `/api/usage/history` | FÅ | Användningshistorik | -| `/api/usage/logs` | FÅ | Användningsloggar | -| `/api/usage/request-logs` | FÅ | Loggar på begäran-nivå | -| `/api/usage/[connectionId]` | FÅ | Användning per anslutning | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Inställningar +### Settings -| Slutpunkt | Metod | Beskrivning | -| ------------------------------- | ------- | ----------------------------------- | -| `/api/settings` | GET/PUT | Allmänna inställningar | -| `/api/settings/proxy` | GET/PUT | Nätverksproxykonfiguration | -| `/api/settings/proxy/test` | POST | Testa proxyanslutning | -| `/api/settings/ip-filter` | GET/PUT | IP-tillståndslista/blockeringslista | -| `/api/settings/thinking-budget` | GET/PUT | Resonera token budget | -| `/api/settings/system-prompt` | GET/PUT | Global systemprompt | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Övervakning +### Monitoring -| Slutpunkt | Metod | Beskrivning | -| ------------------------ | ------------ | ---------------------- | -| `/api/sessions` | FÅ | Aktiv sessionsspårning | -| `/api/rate-limits` | FÅ | Räntegränser per konto | -| `/api/monitoring/health` | FÅ | Hälsokontroll | -| `/api/cache` | HÄMTA/RADERA | Cachestatistik / rensa | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Säkerhetskopiering & export/import +### Backup & Export/Import -| Slutpunkt | Metod | Beskrivning | -| --------------------------- | ----- | ------------------------------------------------------ | -| `/api/db-backups` | FÅ | Lista tillgängliga säkerhetskopior | -| `/api/db-backups` | SÄTT | Skapa en manuell säkerhetskopia | -| `/api/db-backups` | POST | Återställ från en specifik säkerhetskopia | -| `/api/db-backups/export` | FÅ | Ladda ner databas som .sqlite-fil | -| `/api/db-backups/import` | POST | Ladda upp .sqlite-fil för att ersätta databas | -| `/api/db-backups/exportAll` | FÅ | Ladda ner fullständig säkerhetskopia som .tar.gz-arkiv | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | ### Cloud Sync -| Slutpunkt | Metod | Beskrivning | -| ---------------------- | ----- | ------------------------------ | -| `/api/sync/cloud` | Olika | Molnsynkroniseringsoperationer | -| `/api/sync/initialize` | POST | Initiera synkronisering | -| `/api/cloud/*` | Olika | Molnhantering | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI-verktyg +### CLI Tools -| Slutpunkt | Metod | Beskrivning | -| ---------------------------------- | ----- | ------------------- | -| `/api/cli-tools/claude-settings` | FÅ | Claude CLI status | -| `/api/cli-tools/codex-settings` | FÅ | Codex CLI-status | -| `/api/cli-tools/droid-settings` | FÅ | Droid CLI-status | -| `/api/cli-tools/openclaw-settings` | FÅ | OpenClaw CLI-status | -| `/api/cli-tools/runtime/[toolId]` | FÅ | Generisk CLI-körtid | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -CLI-svar inkluderar: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Resiliens och hastighetsgränser +### ACP Agents -| Slutpunkt | Metod | Beskrivning | -| ----------------------- | ------- | ----------------------------------- | -| `/api/resilience` | GET/PUT | Skaffa/uppdatera resiliensprofiler | -| `/api/resilience/reset` | POST | Återställ brytare | -| `/api/rate-limits` | FÅ | Räntegränsstatus per konto | -| `/api/rate-limit` | FÅ | Global hastighetsgränskonfiguration | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | ### Evals -| Slutpunkt | Metod | Beskrivning | -| ------------ | --------- | ------------------------------------------ | -| `/api/evals` | GET/POSTA | Lista utvärderingssviter / kör utvärdering | +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -### Policyer +### Policies -| Slutpunkt | Metod | Beskrivning | -| --------------- | ---------------- | -------------------- | -| `/api/policies` | GET/POSTA/RADERA | Hantera ruttpolicyer | +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -### Efterlevnad +### Compliance -| Slutpunkt | Metod | Beskrivning | -| --------------------------- | ----- | ----------------------------------------- | -| `/api/compliance/audit-log` | FÅ | Granskningslogg för efterlevnad (sista N) | +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### v1beta (Gemini-kompatibel) +### v1beta (Gemini-Compatible) -| Slutpunkt | Metod | Beskrivning | -| -------------------------- | ----- | ---------------------------------- | -| `/v1beta/models` | FÅ | Lista modeller i Gemini-format | -| `/v1beta/models/{...path}` | POST | Gemini `generateContent` slutpunkt | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -Dessa slutpunkter speglar Geminis API-format för klienter som förväntar sig inbyggd Gemini SDK-kompatibilitet. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. -### Interna / System API: er +### Internal / System APIs -| Slutpunkt | Metod | Beskrivning | -| --------------- | ----- | -------------------------------------------------------------- | -| `/api/init` | FÅ | Applikationsinitieringskontroll (används vid första körningen) | -| `/api/tags` | FÅ | Ollama-kompatibla modelltaggar (för Ollama-klienter) | -| `/api/restart` | POST | Utlösa graciös serveromstart | -| `/api/shutdown` | POST | Utlösa graciös serveravstängning | +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | -> **Obs:** Dessa slutpunkter används internt av systemet eller för Ollama-klientkompatibilitet. De anropas vanligtvis inte av slutanvändare. +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Ljudtranskription +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Transkribera ljudfiler med Deepgram eller AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Begäran:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Svar:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -** Leverantörer som stöds:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Format som stöds:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Ollama-kompatibilitet +## Ollama Compatibility -För klienter som använder Ollamas API-format: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Förfrågningar översätts automatiskt mellan Ollama och interna format. +Requests are automatically translated between Ollama and internal formats. --- -## Telemetri +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Svar:** +**Response:** ```json { @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Modelltillgänglighet +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Bearbetning av begäran +## Request Processing -1. Kunden skickar förfrågan till `/v1/*` -2. Rutthanteraren anropar `handleChat`, `handleEmbedding`, `handleAudioTranscription` eller `handleImageGeneration` -3. Modellen är löst (direkt leverantör/modell eller alias/kombo) -4. Inloggningsuppgifter valda från lokal DB med filtrering av kontotillgänglighet -5. För chatt: `handleChatCore` — formatdetektering, översättning, cachekontroll, idempotenskontroll -6. Leverantörs exekutor skickar uppströmsbegäran -7. Svar översatt till klientformat (chatt) eller returnerat som det är (inbäddningar/bilder/ljud) -8. Användning/loggning registrerad -9. Fallback gäller vid fel enligt komboregler +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Fullständig arkitekturreferens: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Autentisering +## Authentication -- Dashboard rutter (`/dashboard/*`) använder `auth_token` cookie -- Inloggning använder sparad lösenordshash; reserv till `INITIAL_PASSWORD` -- `requireLogin` kan växlas via `/api/settings/require-login` -- `/v1/*` rutter kräver valfritt Bearer API-nyckel när `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/sv/ARCHITECTURE.md b/docs/i18n/sv/ARCHITECTURE.md index 7020dd5ad4..258d62df53 100644 --- a/docs/i18n/sv/ARCHITECTURE.md +++ b/docs/i18n/sv/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# OmniRoute-arkitektur +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Senast uppdaterad: 2026-02-18_ +_Last updated: 2026-03-04_ -## Sammanfattning +## Executive Summary -OmniRoute är en lokal AI-routinggateway och instrumentpanel byggd på Next.js. -Den tillhandahåller en enda OpenAI-kompatibel slutpunkt (`/v1/*`) och dirigerar trafik över flera uppströmsleverantörer med översättning, reserv, tokenuppdatering och användningsspårning. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Kärnfunktioner: +Core capabilities: -- OpenAI-kompatibel API-yta för CLI/verktyg (28 leverantörer) -- Begäran/svar översättning över leverantörsformat -- Modellkombination fallback (flermodellsekvens) -- Reservkonto på kontonivå (flera konto per leverantör) -- Anslutningshantering för OAuth + API-nyckelleverantör -- Inbäddningsgenerering via `/v1/embeddings` (6 leverantörer, 9 modeller) -- Bildgenerering via `/v1/images/generations` (4 leverantörer, 9 modeller) -- Tänk taggparsning (`...`) för resonemangsmodeller -- Svarssanering för strikt OpenAI SDK-kompatibilitet -- Rollnormalisering (utvecklare→system, system→användare) för kompatibilitet mellan olika leverantörer -- Strukturerad utdatakonvertering (json_schema → Gemini responseSchema) -- Lokal beständighet för leverantörer, nycklar, alias, kombinationer, inställningar, prissättning -- Användnings-/kostnadsspårning och förfrågningsloggning -- Valfri molnsynkronisering för synkronisering av flera enheter/tillstånd -- IP-godkännandelista/blockeringslista för API-åtkomstkontroll -- Tänkande budgethantering (genomföring/auto/custom/adaptiv) -- Global systeminjektion -- Sessionsspårning och fingeravtryck -- Förbättrad prisbegränsning per konto med leverantörsspecifika profiler -- Strömbrytarmönster för leverantörens motståndskraft -- Åskskyddande flockskydd med mutex-låsning -- Signaturbaserad cache för begärandeduplicering -- Domänlager: modelltillgänglighet, kostnadsregler, reservpolicy, lockoutpolicy -- Beständig domäntillstånd (SQLite-genomskrivningscache för reservdelar, budgetar, lockouter, strömbrytare) -- Policymotor för centraliserad förfrågningsutvärdering (lockout → budget → reserv) -- Begär telemetri med p50/p95/p99 latensaggregation -- Korrelations-ID (X-Request-Id) för spårning från början till slut -- Loggning av efterlevnadsrevision med opt-out per API-nyckel -- Utvärderingsramverk för LLM kvalitetssäkring -- Resilience UI-instrumentpanel med strömbrytarstatus i realtid -- Modulära OAuth-leverantörer (12 individuella moduler under `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Primär körtidsmodell: +Primary runtime model: -- Next.js-apprutter under `src/app/api/*` implementerar både instrumentpanelens API:er och kompatibilitets-API:er -- En delad SSE/routingkärna i `src/sse/*` + `open-sse/*` hanterar leverantörsexekvering, översättning, streaming, reserv och användning +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Omfattning och gränser +## Scope and Boundaries -### I omfattning +### In Scope -- Lokal gateway körtid -- Dashboard management API:er -- Leverantörsautentisering och tokenuppdatering -- Begär översättning och SSE-streaming -- Lokal stat + användningsbeständighet -- Valfri molnsynkroniseringsorkestrering +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Utanför räckvidd +### Out of Scope -- Implementering av molntjänster bakom `NEXT_PUBLIC_CLOUD_URL` -- Leverantör SLA/kontrollplan utanför lokal process -- Externa CLI-binärer själva (Claude CLI, Codex CLI, etc.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Systemkontext på hög nivå +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -115,149 +115,150 @@ flowchart LR ## Core Runtime Components -## 1) API och Routing Layer (Next.js App Routes) +## 1) API and Routing Layer (Next.js App Routes) -Huvudkataloger: +Main directories: -- `src/app/api/v1/*` och `src/app/api/v1beta/*` för kompatibilitets-API:er -- `src/app/api/*` för hanterings-/konfigurations-API:er -- Nästa omskrivning i `next.config.mjs` kartan `/v1/*` till `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Viktiga kompatibilitetsvägar: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — inkluderar anpassade modeller med `custom: true` -- `src/app/api/v1/embeddings/route.ts` — inbäddningsgenerering (6 leverantörer) -- `src/app/api/v1/images/generations/route.ts` — bildgenerering (4+ leverantörer inkl. Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedikerad chatt per leverantör -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedikerade inbäddningar per leverantör -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedikerade bilder per leverantör +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Hanteringsdomäner: +Management domains: -- Auth/inställningar: `src/app/api/auth/*`, `src/app/api/settings/*` -- Leverantörer/anslutningar: `src/app/api/providers*` -- Leverantörsnoder: `src/app/api/provider-nodes*` -- Anpassade modeller: `src/app/api/provider-models` (GET/POST/DELETE) -- Modellkatalog: `src/app/api/models/catalog` (GET) -- Proxykonfiguration: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Nycklar/alias/kombinationer/prissättning: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Användning: `src/app/api/usage/*` -- Synkronisera/moln: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI-verktygshjälpare: `src/app/api/cli-tools/*` -- IP-filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Tänkande budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- Systemprompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessioner: `src/app/api/sessions` (GET) -- Prisgränser: `src/app/api/rate-limits` (GET) -- Motståndskraft: `src/app/api/resilience` (GET/PATCH) — leverantörsprofiler, strömbrytare, hastighetsgränstillstånd -- Återställning av motståndskraft: `src/app/api/resilience/reset` (POST) — återställ brytare + nedkylningar -- Cachestatistik: `src/app/api/cache/stats` (GET/DELETE) -- Modelltillgänglighet: `src/app/api/models/availability` (GET/POST) -- Telemetri: `src/app/api/telemetry/summary` (GET) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) - Budget: `src/app/api/usage/budget` (GET/POST) -- Reservkedjor: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Efterlevnadsrevision: `src/app/api/compliance/audit-log` (GET) -- Evaler: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policyer: `src/app/api/policies` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) ## 2) SSE + Translation Core -Huvudflödesmoduler: +Main flow modules: -- Inträde: `src/sse/handlers/chat.ts` -- Kärnorkestrering: `open-sse/handlers/chatCore.ts` -- Leverantörs exekveringsadaptrar: `open-sse/executors/*` -- Formatidentifiering/leverantörskonfiguration: `open-sse/services/provider.ts` -- Modellanalys/upplösning: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Reservlogik för konto: `open-sse/services/accountFallback.ts` -- Översättningsregister: `open-sse/translator/index.ts` -- Strömomvandlingar: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Användningsextraktion/normalisering: `open-sse/utils/usageTracking.ts` -- Tänk taggtolkare: `open-sse/utils/thinkTagParser.ts` -- Inbäddningshanterare: `open-sse/handlers/embeddings.ts` -- Inbäddningsleverantörsregister: `open-sse/config/embeddingRegistry.ts` -- Hanterare för bildgenerering: `open-sse/handlers/imageGeneration.ts` -- Bildleverantörsregister: `open-sse/config/imageRegistry.ts` -- Svarssanering: `open-sse/handlers/responseSanitizer.ts` -- Rollnormalisering: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Tjänster (affärslogik): +Services (business logic): -- Val av konto/poäng: `open-sse/services/accountSelector.ts` -- Kontextlivscykelhantering: `open-sse/services/contextManager.ts` -- IP-filtertillämpning: `open-sse/services/ipFilter.ts` -- Sessionsspårning: `open-sse/services/sessionManager.ts` -- Begär deduplicering: `open-sse/services/signatureCache.ts` -- Systemprompt injektion: `open-sse/services/systemPrompt.ts` -- Tänkande budgethantering: `open-sse/services/thinkingBudget.ts` -- Jokertecken modell routing: `open-sse/services/wildcardRouter.ts` -- Hantering av prisgränser: `open-sse/services/rateLimitManager.ts` -- Strömbrytare: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Domänlagermoduler: +Domain layer modules: -- Modelltillgänglighet: `src/lib/domain/modelAvailability.ts` -- Kostnadsregler/budgetar: `src/lib/domain/costRules.ts` -- Reservpolicy: `src/lib/domain/fallbackPolicy.ts` -- Kombinationslösare: `src/lib/domain/comboResolver.ts` -- Lockoutpolicy: `src/lib/domain/lockoutPolicy.ts` -- Policymotor: `src/domain/policyEngine.ts` — centraliserad lockout → budget → reservutvärdering -- Felkodskatalog: `src/lib/domain/errorCodes.ts` -- Begärans ID: `src/lib/domain/requestId.ts` -- Timeout för hämtning: `src/lib/domain/fetchTimeout.ts` -- Begär telemetri: `src/lib/domain/requestTelemetry.ts` -- Efterlevnad/revision: `src/lib/domain/compliance/index.ts` -- Eval löpare: `src/lib/domain/evalRunner.ts` -- Beständig domäntillstånd: `src/lib/db/domainState.ts` — SQLite CRUD för reservkedjor, budgetar, kostnadshistorik, lockout-tillstånd, strömbrytare +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth-leverantörsmoduler (12 enskilda filer under `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Registerindex: `src/lib/oauth/providers/index.ts` -- Individuella leverantörer: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, **\*119**, **\_119**, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Tunt omslag: `src/lib/oauth/providers.ts` — återexport från enskilda moduler +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Persistenslager +## 3) Persistence Layer -Primärt tillstånd DB: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- fil: `${DATA_DIR}/db.json` (eller `$XDG_CONFIG_HOME/omniroute/db.json` när inställd, annars `~/.omniroute/db.json`) -- enheter: providerConnections, providerNodes, modelAlias, combos, apiKeys, settings, prissättning, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Användnings-DB: +Usage persistence: -- `src/lib/usageDb.ts` -- filer: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- följer samma baskatalogpolicy som `localDb` (`DATA_DIR`, sedan `XDG_CONFIG_HOME/omniroute` när inställd) -- uppdelad i fokuserade undermoduler: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — CRUD-operationer för domäntillstånd -- Tabeller (skapade i `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Genomskrivningscachemönster: i minneskartor är auktoritativa under körning; mutationer skrivs synkront till SQLite; tillståndet återställs från DB vid kallstart +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) Auth + Säkerhetsytor +## 4) Auth + Security Surfaces -- Dashboard-cookieauth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Generering/verifiering av API-nyckel: `src/shared/utils/apiKey.ts` -- Leverantörshemligheter kvarstod i `providerConnections`-poster -- Utgående proxystöd via `open-sse/utils/proxyFetch.ts` (env vars) och `open-sse/utils/networkProxy.ts` (konfigurerbart per leverantör eller globalt) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Molnsynkronisering +## 5) Cloud Sync -- Schemaläggare init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Periodisk uppgift: `src/shared/services/cloudSyncScheduler.ts` -- Kontrollrutt: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Begär livscykel (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + konto reservflöde +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Reservbeslut drivs av `open-sse/services/accountFallback.ts` med hjälp av statuskoder och felmeddelandeheuristik. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth Onboarding och Token Refresh Lifecycle +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Uppdatering under livetrafik utförs inuti `open-sse/handlers/chatCore.ts` via executorn `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Cloud Sync Lifecycle (Aktivera / Synkronisera / Inaktivera) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Periodisk synkronisering utlöses av `CloudSyncScheduler` när molnet är aktiverat. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Datamodell och lagringskarta +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Fysiska lagringsfiler: +Physical storage files: -- huvudtillstånd: `${DATA_DIR}/db.json` (eller `$XDG_CONFIG_HOME/omniroute/db.json` när inställt, annars `~/.omniroute/db.json`) -- användningsstatistik: `${DATA_DIR}/usage.json` -- begär loggrader: `${DATA_DIR}/log.txt` -- valfria översättare/begäran felsökningssessioner: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Distributionstopologi +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Modulmappning (beslutskritisk) +## Module Mapping (Decision-Critical) -### Rutt- och API-moduler +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: kompatibilitets-API:er -- `src/app/api/v1/providers/[provider]/*`: dedikerade rutter per leverantör (chatt, inbäddningar, bilder) -- `src/app/api/providers*`: leverantör CRUD, validering, testning -- `src/app/api/provider-nodes*`: anpassad kompatibel nodhantering -- `src/app/api/provider-models`: anpassad modellhantering (CRUD) -- `src/app/api/models/catalog`: fullständig modellkatalog API (alla typer grupperade efter leverantör) -- `src/app/api/oauth/*`: OAuth/enhetskod flöden -- `src/app/api/keys*`: lokal API-nyckellivscykel -- `src/app/api/models/alias`: aliashantering -- `src/app/api/combos*`: reservkombohantering -- `src/app/api/pricing`: åsidosättande av prissättning för kostnadsberäkning -- `src/app/api/settings/proxy`: proxykonfiguration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: test av utgående proxyanslutning (POST) -- `src/app/api/usage/*`: API:er för användning och loggar -- `src/app/api/sync/*` + `src/app/api/cloud/*`: molnsynkronisering och molnvända hjälpare -- `src/app/api/cli-tools/*`: lokala CLI-konfigurationsförfattare/checkers -- `src/app/api/settings/ip-filter`: IP-godkännandelista/blockeringslista (GET/PUT) -- `src/app/api/settings/thinking-budget`: budgetkonfig för tänkande token (GET/PUT) -- `src/app/api/settings/system-prompt`: global systemprompt (GET/PUT) -- `src/app/api/sessions`: aktiv sessionslista (GET) -- `src/app/api/rate-limits`: räntegränsstatus per konto (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) ### Routing and Execution Core -- `src/sse/handlers/chat.ts`: begäran om analys, kombinationshantering, kontovalsloop -- `open-sse/handlers/chatCore.ts`: översättning, exekutorutskick, försök igen/uppdatera hantering, strömkonfiguration -- `open-sse/executors/*`: leverantörsspecifikt nätverk och formatbeteende +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Översättningsregister och formatomvandlare +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: översättarregister och orkestrering -- Begär översättare: `open-sse/translator/request/*` -- Svarsöversättare: `open-sse/translator/response/*` -- Formatkonstanter: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Uthållighet +### Persistence -- `src/lib/localDb.ts`: beständig konfiguration/tillstånd -- `src/lib/usageDb.ts`: användningshistorik och rullande förfrågningsloggar +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Provider Executor Täckning (strategimönster) +## Provider Executor Coverage (Strategy Pattern) -Varje leverantör har en specialiserad exekutor som utökar `BaseExecutor` (i `open-sse/executors/base.ts`), som tillhandahåller URL-byggande, rubrikkonstruktion, återförsök med exponentiell backoff, autentiseringsuppdateringskrokar och `execute()` orkestreringsmetoden. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Exekutor | Leverantör(er) | Specialhantering | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamisk URL/header-konfiguration per leverantör | -| `AntigravityExecutor` | Google Antigravity | Anpassade projekt-/sessions-ID:n, försök igen-efter analys | -| `CodexExecutor` | OpenAI Codex | Injicerar systeminstruktioner, tvingar fram resonemang | -| `CursorExecutor` | Markör IDE | ConnectRPC-protokoll, Protobuf-kodning, begäran om signering via kontrollsumma | -| `GithubExecutor` | GitHub Copilot | Copilot token uppdatering, VSCode-härmar rubriker | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binärt format → SSE-konvertering | -| `GeminiCLIExecutor` | Gemini CLI | Uppdateringscykel för Google OAuth-token | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Alla andra leverantörer (inklusive anpassade kompatibla noder) använder `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Leverantörskompatibilitetsmatris +## Provider Compatibility Matrix -| Leverantör | Format | Auth | Streama | Icke-stream | Token Refresh | Användnings-API | -| ---------------- | --------------- | ---------------------- | ---------------- | ----------- | ------------- | --------------------- | -| Claude | claude | API-nyckel / OAuth | ✅ | ✅ | ✅ | ⚠️ Endast admin | -| Tvillingarna | Tvillingarna | API-nyckel / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | -| Antigravitation | antigravitation | OAuth | ✅ | ✅ | ✅ | ✅ Full kvot API | -| OpenAI | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| Codex | openai-svar | OAuth | ✅ tvingad | ❌ | ✅ | ✅ Prisgränser | -| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Kvotbilder | -| Markör | markören | Anpassad kontrollsumma | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Användningsgränser | -| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per förfrågan | -| iFlow | openai | OAuth (Grundläggande) | ✅ | ✅ | ✅ | ⚠️ Per förfrågan | -| OpenRouter | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | claude | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| Mistral | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| Förvirring | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| Tillsammans AI | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| Fireworks AI | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| Cerebras | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| Sammanhålla | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | API-nyckel | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Formatöversättningstäckning +## Format Translation Coverage -Upptäckta källformat inkluderar: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Målformat inkluderar: +Target formats include: -- OpenAI chatt/svar +- OpenAI chat/Responses - Claude -- Gemini/Gemini-CLI/Antigravity kuvert +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Markör +- Cursor -Översättningar använder **OpenAI som navformat** — alla konverteringar går via OpenAI som mellanliggande: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Översättningar väljs dynamiskt baserat på källnyttolastens form och leverantörens målformat. +Translations are selected dynamically based on source payload shape and provider target format. -Ytterligare bearbetningslager i översättningspipelinen: +Additional processing layers in the translation pipeline: -- **Responssanering** — Tar bort icke-standardiserade fält från svar i OpenAI-format (både strömmande och icke-strömmande) för att säkerställa strikt SDK-efterlevnad -- **Rollnormalisering** — Konverterar `developer` → `system` för icke-OpenAI-mål; slår samman `system` → `user` för modeller som avvisar systemrollen (GLM, ERNIE) -- **Tänk taggextraktion** — Parsar `...` block från innehåll till fältet `reasoning_content` -- **Structured output** — Konverterar OpenAI `response_format.json_schema` till Gemini's `responseMimeType` + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## API-slutpunkter som stöds +## Supported API Endpoints -| Slutpunkt | Format | Handlare | -| -------------------------------------------------- | ------------------- | --------------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Meddelanden | Samma hanterare (automatiskt upptäckt) | -| `POST /v1/responses` | OpenAI-svar | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI Inbäddningar | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Modelllista | API-rutt | -| `POST /v1/images/generations` | OpenAI bilder | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Modelllista | API-rutt | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedikerad per leverantör med modellvalidering | -| `POST /v1/providers/{provider}/embeddings` | OpenAI Inbäddningar | Dedikerad per leverantör med modellvalidering | -| `POST /v1/providers/{provider}/images/generations` | OpenAI bilder | Dedikerad per leverantör med modellvalidering | -| `POST /v1/messages/count_tokens` | Claude Token Count | API-rutt | -| `GET /v1/models` | OpenAI-modelllista | API-rutt (chatt + inbäddning + bild + anpassade modeller) | -| `GET /api/models/catalog` | Katalog | Alla modeller grupperade efter leverantör + typ | -| `POST /v1beta/models/*:streamGenerateContent` | Tvillinginfödd | API-rutt | -| `GET/PUT/DELETE /api/settings/proxy` | Proxykonfiguration | Nätverksproxykonfiguration | -| `POST /api/settings/proxy/test` | Proxyanslutning | Proxy hälsa/anslutningstest slutpunkt | -| `GET/POST/DELETE /api/provider-models` | Anpassade modeller | Anpassad modellhantering per leverantör | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Bypass-hanterare +## Bypass Handler -Bypass-hanteraren (`open-sse/utils/bypassHandler.ts`) fångar upp kända "kastningsförfrågningar" från Claude CLI – uppvärmningsping, titelextraktioner och tokenräkningar – och returnerar ett **falskt svar** utan att konsumera uppströmsleverantörstokens. Detta utlöses endast när `User-Agent` innehåller `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Begär Logger Pipeline +## Request Logger Pipeline -Begäranloggaren (`open-sse/utils/requestLogger.ts`) tillhandahåller en 7-stegs felsökningsloggningspipeline, inaktiverad som standard, aktiverad via `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Filer skrivs till `/logs//` för varje begäranssession. +Files are written to `/logs//` for each request session. -## Fellägen och motståndskraft +## Failure Modes and Resilience -## 1) Tillgänglighet för konto/leverantör +## 1) Account/Provider Availability -- Nedkylning av leverantörskonto på övergående/hastighets-/auth-fel -- reservkonto innan begäran misslyckas -- kombimodell fallback när nuvarande modell/leverantörsväg är uttömd +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Tokens utgång +## 2) Token Expiry -- Förkontroll och uppdatera med ett nytt försök för uppdateringsbara leverantörer -- 401/403 försök igen efter uppdateringsförsök i kärnvägen +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Strömsäkerhet +## 3) Stream Safety -- frånkopplingsmedveten strömkontroller -- översättningsström med end-of-stream-spolning och `[DONE]`-hantering -- användningsuppskattning fallback när leverantörens användningsmetadata saknas +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Molnsynkroniseringsförsämring +## 4) Cloud Sync Degradation -- Synkroniseringsfel dyker upp men den lokala körtiden fortsätter -- Schemaläggaren har logik som kan försöka igen, men periodisk exekvering anropar för närvarande synkronisering med ett enda försök som standard +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Dataintegritet +## 5) Data Integrity -- DB-formmigrering/reparation för saknade nycklar -- korrupta JSON-återställningsskydd för localDb och usageDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Observerbarhet och operativa signaler +## Observability and Operational Signals -Källor för synlighet vid körning: +Runtime visibility sources: -- konsolloggar från `src/sse/utils/logger.ts` -- användningsaggregat per begäran i `usage.json` -- textförfrågan status logga in `log.txt` -- valfria djupa förfrågningar/översättningsloggar under `logs/` när `ENABLE_REQUEST_LOGS=true` -- slutpunkter för användning av instrumentpanelen (`/api/usage/*`) för användargränssnittsförbrukning +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Säkerhetskänsliga gränser +## Security-Sensitive Boundaries -- JWT-hemlighet (`JWT_SECRET`) säkrar verifiering/signering av cookies på instrumentpanelen -- Initialt reservlösenord (`INITIAL_PASSWORD`, standard `123456`) måste åsidosättas i verkliga distributioner -- API-nyckel HMAC-hemlighet (`API_KEY_SECRET`) säkrar genererat lokalt API-nyckelformat -- Leverantörshemligheter (API-nycklar/tokens) finns kvar i lokal DB och bör skyddas på filsystemnivå -- Slutpunkter för molnsynkronisering är beroende av API-nyckelbehörighet + maskin-id-semantik +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Miljö- och körtidsmatris +## Environment and Runtime Matrix -Miljövariabler som används aktivt av kod: +Environment variables actively used by code: - App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` -- Lagring: `DATA_DIR` -- Kompatibelt nodbeteende: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Valfri åsidosättning av lagringsbas (Linux/macOS när `DATA_DIR` inte är inställd): `XDG_CONFIG_HOME` -- Säkerhetshashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Loggning: `ENABLE_REQUEST_LOGS` -- Synkronisera/molnwebbadress: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Utgående proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` och varianter med små bokstäver -- SOCKS5-funktionsflaggor: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Plattforms-/runtime-hjälpare (inte appspecifik konfiguration): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Kända arkitektoniska anteckningar +## Known Architectural Notes -1. `usageDb` och `localDb` delar nu samma baskatalogpolicy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) med äldre filmigrering. -2. `/api/v1/route.ts` returnerar en statisk modelllista och är inte den huvudsakliga modellkällan som används av `/v1/models`. -3. Request logger skriver fullständiga rubriker/text när den är aktiverad; behandla loggkatalogen som känslig. -4. Molnets beteende beror på korrekt `NEXT_PUBLIC_BASE_URL` och molnets slutpunkts tillgänglighet. -5. Katalogen `open-sse/` publiceras som `@omniroute/open-sse` **npm workspace-paketet**. Källkoden importerar den via `@omniroute/open-sse/...` (löst av Next.js `transpilePackages`). Filsökvägar i det här dokumentet använder fortfarande katalognamnet `open-sse/` för konsekvens. -6. Diagram i instrumentpanelen använder **Recharts** (SVG-baserad) för tillgängliga, interaktiva analysvisualiseringar (stapeldiagram för modellanvändning, leverantörsuppdelningstabeller med framgångsfrekvenser). -7. E2E-tester använder **dramatiker** (`tests/e2e/`), körs via `npm run test:e2e`. Enhetstester använder **Node.js testrunner** (`tests/unit/`), körs via `npm run test:plan3`. Källkoden under `src/` är **TypeScript** (`.ts`/`.tsx`); arbetsytan `open-sse/` förblir JavaScript (`.js`). -8. Inställningssidan är organiserad i 5 flikar: Säkerhet, Routing (6 globala strategier: fill-first, round-robin, p2c, slumpmässig, minst använda, kostnadsoptimerad), Resiliens (redigerbara hastighetsgränser, strömbrytare, policyer), AI (tänkande budget, systemprompt, promptcache), Advanced (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Checklista för operativ verifiering +## Operational Verification Checklist -- Bygg från källa: `npm run build` -- Bygg Docker-bild: `docker build -t omniroute .` -- Starta tjänsten och verifiera: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- CLI-målbasadressen ska vara `http://:20128/v1` när `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/sv/CODEBASE_DOCUMENTATION.md b/docs/i18n/sv/CODEBASE_DOCUMENTATION.md index 59431248a2..303880c198 100644 --- a/docs/i18n/sv/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/sv/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Kodbasdokumentation +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> En omfattande, nybörjarvänlig guide till **omniroute** AI-proxyrouter med flera leverantörer. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Vad är omniroute? +## 1. What Is omniroute? -omniroute är en **proxyrouter** som sitter mellan AI-klienter (Claude CLI, Codex, Cursor IDE, etc.) och AI-leverantörer (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Det löser ett stort problem: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Olika AI-klienter talar olika "språk" (API-format), och olika AI-leverantörer förväntar sig också olika "språk".** omniroute översätter mellan dem automatiskt. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Tänk på det som en universell översättare vid Förenta Nationerna - vilken delegat som helst kan tala vilket språk som helst, och översättaren konverterar det till vilken annan delegat som helst. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Arkitekturöversikt +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Kärnprincip: Översättning av nav och eker +### Core Principle: Hub-and-Spoke Translation -All formatöversättning går genom **OpenAI-formatet som navet**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Det betyder att du bara behöver **N översättare** (en per format) istället för **N²** (varje par). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Projektets struktur +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Uppdelning av modul för modul +## 4. Module-by-Module Breakdown ### 4.1 Config (`open-sse/config/`) -Den **enda källan till sanning** för alla leverantörskonfigurationer. +The **single source of truth** for all provider configuration. -| Arkiv | Syfte | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` objekt med bas-URL:er, OAuth-referenser (standard), rubriker och standardsystemuppmaningar för varje leverantör. Definierar även `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` och `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Laddar externa referenser från `data/provider-credentials.json` och slår samman dem över de hårdkodade standardinställningarna i `PROVIDERS`. Håller hemligheter utom källans kontroll samtidigt som bakåtkompatibiliteten bibehålls. | -| `providerModels.ts` | Centralt modellregister: kartleverantörsalias → modell-ID:n. Funktioner som `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Systeminstruktioner injicerade i Codex-förfrågningar (redigeringsbegränsningar, sandlåderegler, godkännandepolicyer). | -| `defaultThinkingSignature.ts` | Standard "tänkande" signaturer för Claude och Gemini modeller. | -| `ollamaModels.ts` | Schemadefinition för lokala Ollama-modeller (namn, storlek, familj, kvantisering). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Behörighetsladdningsflöde +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Exekutorer (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Exekutorer kapslar in **leverantörsspecifik logik** med hjälp av **Strategy Pattern**. Varje executor åsidosätter basmetoder efter behov. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Exekutor | Leverantör | Nyckelspecialiseringar | -| ---------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Abstrakt bas: URL-byggnad, rubriker, logik för försök igen, uppdatering av autentiseringsuppgifter | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generisk OAuth-tokenuppdatering för standardleverantörer | -| `antigravity.ts` | Google Cloud Code | Generering av projekt-/sessions-ID, reserv för flera webbadresser, anpassad försök att analysera igen från felmeddelanden ("återställ efter 2h7m23s") | -| `cursor.ts` | Markör IDE | **Mest komplex**: SHA-256 kontrollsummaauth, Protobuf-begärankodning, binär EventStream → SSE-svarsanalys | -| `codex.ts` | OpenAI Codex | Injicerar systeminstruktioner, hanterar tankenivåer, tar bort parametrar som inte stöds | -| `gemini-cli.ts` | Google Gemini CLI | Byggande av anpassad webbadress (`streamGenerateContent`), uppdatering av Google OAuth-token | -| `github.ts` | GitHub Copilot | Dubbla tokensystem (GitHub OAuth + Copilot-token), VSCode-huvudhärmare | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binär analys, AMZN-händelseramar, tokenuppskattning | -| `index.ts` | — | Fabrik: maps provider name → executor class, with default fallback | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Hanterare (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**orkestreringsskiktet** — koordinerar översättning, exekvering, streaming och felhantering. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Arkiv | Syfte | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Centralorkester** (~600 rader). Hanterar hela begärans livscykel: formatdetektering → översättning → exekutorutskick → strömmande/icke-strömmande svar → tokenuppdatering → felhantering → användningsloggning. | -| `responsesHandler.ts` | Adapter för OpenAI:s Responses API: konverterar svarsformat → Chattavslut → skickar till `chatCore` → konverterar SSE tillbaka till svarsformat. | -| `embeddings.ts` | Inbäddningsgenereringshanterare: löser inbäddningsmodell → leverantör, skickar till leverantörs API, returnerar OpenAI-kompatibelt inbäddningssvar. Stöder 6+ leverantörer. | -| `imageGeneration.ts` | Bildgenereringshanterare: löser bildmodell → leverantör, stöder OpenAI-kompatibla, Gemini-bild (Antigravity) och reservläge (Nebius). Returnerar base64- eller URL-bilder. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Begär livscykel (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,26 +258,26 @@ sequenceDiagram --- -### 4.4 Tjänster (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Affärslogik som stödjer hanterarna och utförarna. +Business logic that supports the handlers and executors. -| Arkiv | Syfte | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `provider.ts` | **Formatdetektering** (`detectFormat`): analyserar begäran om kroppsstruktur för att identifiera Claude/OpenAI/Gemini/Antigravity/Responses-format (inkluderar `max_tokens` heuristik för Claude). Dessutom: URL-byggande, header-byggande, normalisering av tankekonfiguration. Stöder `openai-compatible-*` och `anthropic-compatible-*` dynamiska leverantörer. | -| `model.ts` | Modellsträngsanalys (`claude/model-name` → `{provider: "claude", model: "model-name"}`), aliasupplösning med kollisionsdetektering, ingångssanering (avvisar vägövergång/kontrolltecken) och modellinformationsupplösning med stöd för asynkront alias getter. | -| `accountFallback.ts` | Hantering av hastighetsgränser: exponentiell backoff (1s → 2s → 4s → max 2min), hantering av kontonedkylning, felklassificering (vilka fel utlöser fallback kontra inte). | -| `tokenRefresh.ts` | OAuth-tokenuppdatering för **alla leverantörer**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Inkluderar löftesdedupliceringscache under flygning och försök igen med exponentiell backoff. | -| `combo.ts` | **Kombomodeller**: kedjor av reservmodeller. Om modell A misslyckas med ett fallback-berättigat fel, prova modell B, sedan C osv. Returnerar faktiska uppströmsstatuskoder. | -| `usage.ts` | Hämtar kvot/användningsdata från leverantörens API:er (GitHub Copilot-kvoter, Antigravity-modellkvoter, Codex-hastighetsgränser, Kiro-användningsuppdelningar, Claude-inställningar). | -| `accountSelector.ts` | Smart kontoval med poängalgoritm: tar hänsyn till prioritet, hälsostatus, round-robin-position och nedkylningsläge för att välja det optimala kontot för varje begäran. | -| `contextManager.ts` | Begär kontext livscykelhantering: skapar och spårar per begäran kontextobjekt med metadata (begäran ID, tidsstämplar, leverantörsinformation) för felsökning och loggning. | -| `ipFilter.ts` | IP-baserad åtkomstkontroll: stöder tillstånds- och blockeringslägen. Validerar klient-IP mot konfigurerade regler innan API-förfrågningar behandlas. | -| `sessionManager.ts` | Sessionsspårning med klientfingeravtryck: spårar aktiva sessioner med hashade klientidentifierare, övervakar antalet begäranden och tillhandahåller sessionsstatistik. | -| `signatureCache.ts` | Begär signaturbaserad dedupliceringscache: förhindrar dubbletter av begäranden genom att cachelagra senaste begäransignaturer och returnera cachade svar för identiska förfrågningar inom ett tidsfönster. | -| `systemPrompt.ts` | Global systempromptinjektion: lägger till eller lägger till en konfigurerbar systemprompt till alla förfrågningar, med kompatibilitetshantering per leverantör. | -| `thinkingBudget.ts` | Hantering av resonerande tokenbudget: stöder passthrough, auto (strip thinking config), anpassade (fast budget) och adaptiva (komplexitetsskalade) lägen för att kontrollera tänkande/resonemangstokens. | -| `wildcardRouter.ts` | Jokerteckenmodellmönsterrouting: löser jokerteckenmönster (t.ex. `*/claude-*`) till konkreta leverantör/modellpar baserat på tillgänglighet och prioritet. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | #### Token Refresh Deduplication @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Konto reservtillståndsmaskin +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Kombinerad modellkedja +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Översättare (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**formatöversättningsmotorn** använder ett självregistrerande pluginsystem. +The **format translation engine** using a self-registering plugin system. -#### Arkitektur +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Katalog | Filer | Beskrivning | -| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 översättare | Konvertera begärandekroppar mellan format. Varje fil självregistreras via `register(from, to, fn)` vid import. | -| `response/` | 7 översättare | Konvertera strömmande svarsbitar mellan format. Hanterar SSE-händelsetyper, tankeblock, verktygsanrop. | -| `helpers/` | 6 hjälpare | Delade verktyg: `claudeHelper` (extrahering av systemprompt, tankekonfiguration), `geminiHelper` (mappning av delar/innehåll), `openaiHelper` (formatfiltrering), `toolCallHelper` (ID-generering, injektion av saknat svar), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Översättningsmotor: `translateRequest()`, `translateResponse()`, statlig ledning, register. | -| `formats.ts` | — | Formatkonstanter: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Nyckeldesign: Självregistrerande plugins +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -397,15 +397,15 @@ import "./request/claude-to-openai.js"; // ← self-registers ### 4.6 Utils (`open-sse/utils/`) -| Arkiv | Syfte | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `error.ts` | Byggande av felsvar (OpenAI-kompatibelt format), uppströms felanalys, Antigravity-återförsöksextraktion från felmeddelanden, SSE-felströmning. | -| `stream.ts` | **SSE Transform Stream** — kärnan för streaming. Två lägen: `TRANSLATE` (översättning i fullformat) och `PASSTHROUGH` (normalisera + extrahera användning). Hanterar chunkbuffring, användningsuppskattning, spårning av innehållslängd. Encoder/decoder-instanser per ström undviker delat tillstånd. | -| `streamHelpers.ts` | SSE-verktyg på låg nivå: `parseSSELine` (tolerant för blanksteg), `hasValuableContent` (filtrerar tomma bitar för OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (formatmedveten SSE-serialisering med med ). | -| `usageTracking.ts` | Extrahering av tokenanvändning från valfritt format (Claude/OpenAI/Gemini/Responses), uppskattning med separata verktyg/meddelande-char-per-token-förhållanden, bufferttillägg (säkerhetsmarginal för 2000 tokens), formatspecifik fältfiltrering, konsolloggning med ANSI-färger. | -| `requestLogger.ts` | Filbaserad förfrågningsloggning (opt-in via `ENABLE_REQUEST_LOGS=true`). Skapar sessionsmappar med numrerade filer: `1_req_client.json` → `7_res_client.txt`. All I/O är asynkron (eld-och-glöm). Maskerar känsliga rubriker. | -| `bypassHandler.ts` | Fångar upp specifika mönster från Claude CLI (titelextraktion, uppvärmning, räkning) och returnerar falska svar utan att ringa någon leverantör. Stöder både streaming och icke-streaming. Avsiktligt begränsad till Claude CLI omfattning. | -| `networkProxy.ts` | Löser utgående proxy-URL för en given leverantör med prioritet: leverantörsspecifik konfiguration → global konfiguration → miljövariabler (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Stöder `NO_PROXY` undantag. Caches konfiguration för 30s. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | #### SSE Streaming Pipeline @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Begär Logger Session Struktur +#### Request Logger Session Structure ``` logs/ @@ -449,107 +449,107 @@ logs/ ### 4.7 Application Layer (`src/`) -| Katalog | Syfte | -| ------------- | -------------------------------------------------------------------------------------- | -| `src/app/` | Webbgränssnitt, API-rutter, Express-mellanprogramvara, OAuth-återuppringningshanterare | -| `src/lib/` | Databasåtkomst (`localDb.ts`, `usageDb.ts`), autentisering, delad | -| `src/mitm/` | Man-in-the-middle-proxyverktyg för att avlyssna leverantörstrafik | -| `src/models/` | Databasmodelldefinitioner | -| `src/shared/` | Omslag runt öppna-sse-funktioner (leverantör, stream, fel, etc.) | -| `src/sse/` | SSE-slutpunktshanterare som kopplar open-sse-biblioteket till Express-rutter | -| `src/store/` | Tillståndshantering för applikationer | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Anmärkningsvärda API-rutter +#### Notable API Routes -| Rutt | Metoder | Syfte | -| --------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | GET/POSTA/RADERA | CRUD för anpassade modeller per leverantör | -| `/api/models/catalog` | FÅ | Aggregerad katalog över alla modeller (chatt, inbäddning, bild, anpassad) grupperade efter leverantör | -| `/api/settings/proxy` | GET/PUT/DELETE | Hierarkisk utgående proxykonfiguration (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | POST | Validerar proxyanslutning och returnerar offentlig IP/latency | -| `/v1/providers/[provider]/chat/completions` | POST | Dedikerade chattkompletteringar per leverantör med modellvalidering | -| `/v1/providers/[provider]/embeddings` | POST | Dedikerade inbäddningar per leverantör med modellvalidering | -| `/v1/providers/[provider]/images/generations` | POST | Dedikerad bildgenerering per leverantör med modellvalidering | -| `/api/settings/ip-filter` | GET/PUT | Hantering av IP-tillståndslistor/blockeringslistor | -| `/api/settings/thinking-budget` | GET/PUT | Resonemangstokens budgetkonfiguration (passthrough/auto/custom/adaptive) | -| `/api/settings/system-prompt` | GET/PUT | Global systeminjektion för alla förfrågningar | -| `/api/sessions` | FÅ | Aktiv sessionsspårning och mätvärden | -| `/api/rate-limits` | FÅ | Räntegränsstatus per konto | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Nyckeldesignmönster +## 5. Key Design Patterns -### 5.1 Hub-and-Speake-översättning +### 5.1 Hub-and-Spoke Translation -Alla format översätts genom **OpenAI-formatet som navet**. Att lägga till en ny leverantör kräver bara att man skriver **ett par** översättare (till/från OpenAI), inte N par. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Exekutorstrategimönster +### 5.2 Executor Strategy Pattern -Varje leverantör har en dedikerad executor-klass som ärver från `BaseExecutor`. Fabriken i `executors/index.ts` väljer rätt vid körning. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Självregistrerande pluginsystem +### 5.3 Self-Registering Plugin System -Översättningsmoduler registrerar sig själva vid import via `register()`. Att lägga till en ny översättare är bara att skapa en fil och importera den. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Kontoåtgång med exponentiell backoff +### 5.4 Account Fallback with Exponential Backoff -När en leverantör returnerar 429/401/500 kan systemet byta till nästa konto genom att tillämpa exponentiell nedkylning (1s → 2s → 4s → max 2min). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Combo modellkedjor +### 5.5 Combo Model Chains -En "combo" grupperar flera `provider/model`-strängar. Om den första misslyckas, återgå automatiskt till nästa. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. ### 5.6 Stateful Streaming Translation -Svarsöversättning upprätthåller tillstånd över SSE-bitar (tänkeblockspårning, verktygsanropsackumulering, innehållsblockindexering) via mekanismen `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Användningssäkerhetsbuffert +### 5.7 Usage Safety Buffer -En buffert på 2000 token läggs till rapporterad användning för att förhindra att klienter når kontextfönstergränser på grund av overhead från systemuppmaningar och formatöversättning. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Format som stöds +## 6. Supported Formats -| Format | Riktning | Identifierare | -| --------------------- | ----------- | ------------------ | -| OpenAI Chat Slutförda | källa + mål | `openai` | -| OpenAI Responses API | källa + mål | `openai-responses` | -| Antropisk Claude | källa + mål | `claude` | -| Google Tvillingarna | källa + mål | `gemini` | -| Google Gemini CLI | endast mål | `gemini-cli` | -| Antigravitation | källa + mål | `antigravity` | -| AWS Kiro | endast mål | `kiro` | -| Markör | endast mål | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Leverantörer som stöds +## 7. Supported Providers -| Leverantör | Auth Method | Exekutor | Viktiga anmärkningar | -| ------------------------ | ------------------------------ | --------------- | --------------------------------------------------------------------- | -| Antropisk Claude | API-nyckel eller OAuth | Standard | Använder `x-api-key` header | -| Google Tvillingarna | API-nyckel eller OAuth | Standard | Använder `x-goog-api-key` header | -| Google Gemini CLI | OAuth | GeminiCLI | Använder `streamGenerateContent` slutpunkt | -| Antigravitation | OAuth | Antigravitation | Alternativ för flera webbadresser, anpassad försök att analysera igen | -| OpenAI | API-nyckel | Standard | Standardbärare auth | -| Codex | OAuth | Codex | Injicerar systeminstruktioner, hanterar tänkande | -| GitHub Copilot | OAuth + Copilot-token | Github | Dubbla token, VSCode-huvudhärmar | -| Kiro (AWS) | AWS SSO OIDC eller Social | Kiro | Binär EventStream-analys | -| Markör IDE | Kontrollsumma auth | Markör | Protobuf-kodning, SHA-256 kontrollsummor | -| Qwen | OAuth | Standard | Standardauth | -| iFlow | OAuth (Grundläggande + Bärare) | Standard | Dubbla autentiseringshuvud | -| OpenRouter | API-nyckel | Standard | Standardbärare auth | -| GLM, Kimi, MiniMax | API-nyckel | Standard | Claude-kompatibel, använd `x-api-key` | -| `openai-compatible-*` | API-nyckel | Standard | Dynamisk: alla OpenAI-kompatibla slutpunkter | -| `anthropic-compatible-*` | API-nyckel | Standard | Dynamisk: valfri Claude-kompatibel slutpunkt | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Dataflödessammanfattning +## 8. Data Flow Summary -### Strömningsförfrågan +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Begäran om icke-streaming +### Non-Streaming Request ```mermaid flowchart LR diff --git a/docs/i18n/sv/FEATURES.md b/docs/i18n/sv/FEATURES.md index d3ac50c3b0..82cc73b67b 100644 --- a/docs/i18n/sv/FEATURES.md +++ b/docs/i18n/sv/FEATURES.md @@ -1,14 +1,14 @@ -# OmniRoute — Dashboard Funktionsgalleri +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Visuell guide till varje avsnitt av OmniRoute-instrumentpanelen. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Leverantörer +## 🔌 Providers -Hantera AI-leverantörsanslutningar: OAuth-leverantörer (Claude Code, Codex, Gemini CLI), API-nyckelleverantörer (Groq, DeepSeek, OpenRouter) och gratisleverantörer (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) @@ -16,7 +16,7 @@ Hantera AI-leverantörsanslutningar: OAuth-leverantörer (Claude Code, Codex, Ge ## 🎨 Combos -Skapa modell routing (model aliases, background task degradation)-kombinationer med 6 strategier: fyll först, round-robin, kraft-av-två-val, slumpmässig, minst använda och kostnadsoptimerad. Varje combo kedjer flera modeller med automatisk reserv. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) @@ -24,54 +24,119 @@ Skapa modell routing (model aliases, background task degradation)-kombinationer ## 📊 Analytics -Omfattande användningsanalys med tokenförbrukning, kostnadsberäkningar, aktivitetsvärmekartor, veckofördelningsdiagram och uppdelningar per leverantör. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Systemhälsa +## 🏥 System Health -Realtidsövervakning: drifttid, minne, version, latenspercentiler (p50/p95/p99), cachestatistik och leverantörs strömbrytartillstånd. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Översättarlekplats +## 🔧 Translator Playground -Fyra lägen för att felsöka API-översättningar: **Lekplats** (formatomvandlare), **Chatttestare** (liveförfrågningar), **Testbänk** (batchtester) och **Live Monitor** (strömning i realtid). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Inställningar +## 🎮 Model Playground _(v2.0.9+)_ -Allmänna inställningar, systemlagring, säkerhetskopieringshantering (export/import-databas), utseende (mörkt/ljusläge), säkerhet (inkluderar API-ändpunktsskydd och anpassad leverantörsblockering), routing, motståndskraft och avancerad konfiguration. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI-verktyg +## 🔧 CLI Tools -Konfiguration med ett klick för AI-kodningsverktyg: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code och Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Begärloggar +## 🤖 CLI Agents _(v2.0.11+)_ -Loggning av förfrågningar i realtid med filtrering efter leverantör, modell, konto och API-nyckel. Visar statuskoder, tokenanvändning, latens och svarsdetaljer. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API-slutpunkt +## 🌐 API Endpoint -Din enhetliga API-slutpunkt med kapacitetsuppdelning: Chattavslut, inbäddningar, bildgenerering, omrankning, ljudtranskription och registrerade API-nycklar. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/sv/TROUBLESHOOTING.md b/docs/i18n/sv/TROUBLESHOOTING.md index 4ffefb2ad1..120092d63c 100644 --- a/docs/i18n/sv/TROUBLESHOOTING.md +++ b/docs/i18n/sv/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Felsökning +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Vanliga problem och lösningar för OmniRoute. +Common problems and solutions for OmniRoute. --- -## Snabbfixar +## Quick Fixes -| Problem | Lösning | -| ------------------------------------- | --------------------------------------------------------------------------- | -| Första inloggningen fungerar inte | Markera `INITIAL_PASSWORD` i `.env` (standard: `123456`) | -| Instrumentpanelen öppnas vid fel port | Ställ in `PORT=20128` och `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Inga förfrågningsloggar under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: tillstånd nekad | Ställ in `DATA_DIR=/path/to/writable/dir` för att åsidosätta `~/.omniroute` | -| Routingstrategi sparas inte | Uppdatering till v1.4.11+ (Zod-schemafix för inställningsbeständighet) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Leverantörsproblem +## Provider Issues -### "Språkmodellen gav inga meddelanden" +### "Language model did not provide messages" -**Orsak:** Leverantörskvoten är slut. +**Cause:** Provider quota exhausted. -**Åtgärda:** +**Fix:** -1. Kontrollera instrumentpanelens kvotspårare -2. Använd en kombination med reservnivåer -3. Byt till billigare/gratis nivå +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Prisbegränsande +### Rate Limiting -**Orsak:** Prenumerationskvoten är slut. +**Cause:** Subscription quota exhausted. -**Åtgärda:** +**Fix:** -- Lägg till reserv: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Använd GLM/MiniMax som billig backup +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth-token har löpt ut +### OAuth Token Expired -OmniRoute uppdaterar automatiskt tokens. Om problemen kvarstår: +OmniRoute auto-refreshes tokens. If issues persist: -1. Instrumentpanel → Leverantör → Återanslut -2. Ta bort och lägg till leverantörsanslutningen igen +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Molnproblem +## Cloud Issues -### Cloud Sync-fel +### Cloud Sync Errors -1. Verifiera att `BASE_URL` pekar på din löpinstans (t.ex. `http://localhost:20128`) -2. Verifiera `CLOUD_URL` punkter till din molnslutpunkt (t.ex. `https://omniroute.dev`) -3. Håll `NEXT_PUBLIC_*`-värdena i linje med värden på serversidan +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Returnerar 500 +### Cloud `stream=false` Returns 500 -**Symptom:** `Unexpected token 'd'...` på molnets slutpunkt för icke-strömmande samtal. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Orsak:** Uppströms returnerar SSE-nyttolast medan klienten förväntar sig JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Lösning:** Använd `stream=true` för direkta molnsamtal. Lokal körtid inkluderar SSE→JSON reserv. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud säger ansluten men "Ogiltig API-nyckel" +### Cloud Says Connected but "Invalid API key" -1. Skapa en ny nyckel från den lokala instrumentpanelen (`/api/keys`) -2. Kör molnsynkronisering: Aktivera moln → Synkronisera nu -3. Gamla/icke-synkroniserade nycklar kan fortfarande returnera `401` på molnet +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Docker-problem +## Docker Issues -### CLI-verktyget visar inte installerat +### CLI Tool Shows Not Installed -1. Kontrollera körtidsfält: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. För portabelt läge: använd bildmål `runner-cli` (buntade CLI) -3. För värdmonteringsläge: ställ in `CLI_EXTRA_PATHS` och montera host bin-katalogen som skrivskyddad -4. Om `installed=true` och `runnable=false`: binär hittades men misslyckades med hälsokontrollen +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Snabb körtidsvalidering +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Kostnadsfrågor +## Cost Issues -### Höga kostnader +### High Costs -1. Kontrollera användningsstatistik i Dashboard → Användning -2. Byt primärmodell till GLM/MiniMax -3. Använd gratis nivå (Gemini CLI, iFlow) för icke-kritiska uppgifter -4. Ställ in kostnadsbudgetar per API-nyckel: Dashboard → API-nycklar → Budget +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Felsökning +## Debugging -### Aktivera förfrågningsloggar +### Enable Request Logs -Ställ in `ENABLE_REQUEST_LOGS=true` i din `.env`-fil. Loggar visas under katalogen `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Kontrollera leverantörens hälsa +### Check Provider Health ```bash # Health dashboard @@ -120,100 +120,135 @@ curl http://localhost:20128/api/monitoring/health ### Runtime Storage -- Huvudstatus: `${DATA_DIR}/db.json` (leverantörer, kombinationer, alias, nycklar, inställningar) -- Användning: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Begäran loggar: `/logs/...` (när `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Problem med strömbrytare +## Circuit Breaker Issues -### Leverantören har fastnat i ÖPPET läge +### Provider stuck in OPEN state -När en leverantörs strömbrytare är ÖPPEN, blockeras förfrågningar tills nedkylningen går ut. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Åtgärda:** +**Fix:** -1. Gå till **Dashboard → Inställningar → Resilience** -2. Kontrollera strömbrytarkortet för den berörda leverantören -3. Klicka på **Återställ alla** för att rensa alla brytare, eller vänta tills nedkylningen löper ut -4. Kontrollera att leverantören faktiskt är tillgänglig innan du återställer +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Leverantören löser ut strömbrytaren hela tiden +### Provider keeps tripping the circuit breaker -Om en leverantör upprepade gånger går in i ÖPPET läge: +If a provider repeatedly enters OPEN state: -1. Kontrollera **Dashboard → Health → Provider Health** för felmönstret -2. Gå till **Inställningar → Resiliens → Leverantörsprofiler** och höj feltröskeln -3. Kontrollera om leverantören har ändrat API-gränser eller kräver omautentisering -4. Granska latenstelemetri — hög latens kan orsaka timeoutbaserade fel +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Ljudtranskriptionsproblem +## Audio Transcription Issues -### Felet "Modellen stöds inte". +### "Unsupported model" error -- Se till att du använder rätt prefix: `deepgram/nova-3` eller `assemblyai/best` -- Kontrollera att leverantören är ansluten i **Dashboard → Leverantörer** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Transkription returnerar tom eller misslyckas +### Transcription returns empty or fails -- Kontrollera ljudformat som stöds: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Kontrollera att filstorleken ligger inom leverantörens gränser (vanligtvis < 25 MB) -- Kontrollera giltigheten av leverantörens API-nyckel i leverantörskortet +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Översättarfelsökning +## Translator Debugging -Använd **Dashboard → Översättare** för att felsöka formatöversättningsproblem: +Use **Dashboard → Translator** to debug format translation issues: -| Läge | När ska man använda | -| ---------------- | ----------------------------------------------------------------------------------------------------- | -| **Lekplats** | Jämför in-/utdataformat sida vid sida — klistra in en misslyckad begäran för att se hur den översätts | -| **Chatttestare** | Skicka livemeddelanden och inspektera hela nyttolasten för begäran/svar inklusive rubriker | -| **Testbänk** | Kör batchtester över formatkombinationer för att hitta vilka översättningar som är trasiga | -| **Live Monitor** | Se förfrågningsflödet i realtid för att fånga intermittenta översättningsproblem | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Vanliga formatproblem +### Common format issues -- **Tänketaggar visas inte** — Kontrollera om målleverantören stöder tänkande och inställningen av tänkande budget -- **Verktygsanrop avbryts** — Vissa formatöversättningar kan ta bort fält som inte stöds; verifiera i Playground-läge -- **Systemprompt saknas** — Claude och Gemini hanterar systemprompter på olika sätt; kontrollera översättningsutdata -- **SDK returnerar obearbetad sträng istället för objekt** — Fixat i v1.1.0: Response Sanizer tar nu bort icke-standardiserade fält (`x_groq`, `usage_breakdown`, etc.) som orsakar OpenAI SDK Pydantic valideringsfel -- **GLM/ERNIE avvisar rollen `system`** — Fixat i v1.1.0: rollnormaliseraren slår automatiskt samman systemmeddelanden till användarmeddelanden för inkompatibla modeller -- **`developer` roll inte igenkänd** — Fixad i v1.1.0: konverteras automatiskt till `system` för icke-OpenAI-leverantörer -- **`json_schema` fungerar inte med Gemini** — Fixat i v1.1.0: `response_format` har nu konverterats till Geminis `responseMimeType` + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Resiliensinställningar +## Resilience Settings -### Den automatiska hastighetsgränsen utlöses inte +### Auto rate-limit not triggering -- Automatisk hastighetsgräns gäller endast API-nyckelleverantörer (inte OAuth/prenumeration) -- Verifiera att **Inställningar → Motståndskraft → Leverantörsprofiler** har aktiverat automatisk hastighetsgräns -- Kontrollera om leverantören returnerar `429` statuskoder eller `Retry-After` rubriker +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Tuning exponentiell backoff +### Tuning exponential backoff -Leverantörsprofiler stöder dessa inställningar: +Provider profiles support these settings: -- **Basfördröjning** — Initial väntetid efter första fel (standard: 1 s) -- **Max fördröjning** — Maximalt väntetidstak (standard: 30s) -- **Multiplikator** — Hur mycket ska fördröjningen öka per på varandra följande fel (standard: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Anti-dundrande flock +### Anti-thundering herd -När många samtidiga förfrågningar träffar en hastighetsbegränsad leverantör, använder OmniRoute mutex + automatisk hastighetsbegränsning för att serialisera förfrågningar och förhindra kaskadfel. Detta är automatiskt för API-nyckelleverantörer. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Fortfarande fast? +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub-problem**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Arkitektur**: Se [link](ARCHITECTURE.md) för interna detaljer -- **API-referens**: Se [link](API_REFERENCE.md) för alla slutpunkter -- **Hälsa Dashboard**: Kontrollera **Dashboard → Health** för systemstatus i realtid -- **Översättare**: Använd **Dashboard → Översättare** för att felsöka formatproblem +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/sv/USER_GUIDE.md b/docs/i18n/sv/USER_GUIDE.md index 067bea5b81..5a043224df 100644 --- a/docs/i18n/sv/USER_GUIDE.md +++ b/docs/i18n/sv/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Användarhandbok +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Komplett guide för att konfigurera leverantörer, skapa kombinationer, integrera CLI-verktyg och distribuera OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Innehållsförteckning +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Komplett guide för att konfigurera leverantörer, skapa kombinationer, integrer --- -## 💰 Prissättning i en överblick +## 💰 Pricing at a Glance -| Nivå | Leverantör | Kostnad | Kvotåterställning | Bäst för | -| -------------------- | ----------------- | --------------------- | ------------------------ | -------------------------- | -| **💳 PRENUMERATION** | Claude Code (Pro) | 20 USD/månad | 5h + veckovis | Har redan prenumererat | -| | Codex (Plus/Pro) | 20-200 USD/månad | 5h + veckovis | OpenAI-användare | -| | Gemini CLI | **GRATIS** | 180K/månad + 1K/dag | Alla! | -| | GitHub Copilot | 10-19 USD/månad | Månatlig | GitHub-användare | -| **🔑 API-NYCKEL** | DeepSeek | Betala per användning | Inga | Billigt resonemang | -| | Groq | Betala per användning | Inga | Ultrasnabb slutledning | -| | xAI (Grok) | Betala per användning | Inga | Grok 4 resonemang | -| | Mistral | Betala per användning | Inga | EU-värdade modeller | -| | Förvirring | Betala per användning | Inga | Sökförstärkt | -| | Tillsammans AI | Betala per användning | Inga | Modeller med öppen källkod | -| | Fireworks AI | Betala per användning | Inga | Fast FLUX bilder | -| | Cerebras | Betala per användning | Inga | Wafer-skala hastighet | -| | Sammanhålla | Betala per användning | Inga | Kommando R+ RAG | -| | NVIDIA NIM | Betala per användning | Inga | Företagsmodeller | -| **💰 BILLIGT** | GLM-4.7 | $0,6/1M | Dagligen 10:00 | Budget backup | -| | MiniMax M2.1 | $0,2/1M | 5-timmars rullande | Billigaste alternativet | -| | Kimi K2 | 9 USD/mån lägenhet | 10 miljoner tokens/månad | Förutsägbar kostnad | -| **🆓 GRATIS** | iFlow | $0 | Obegränsad | 8 modeller gratis | -| | Qwen | $0 | Obegränsad | 3 modeller gratis | -| | Kiro | $0 | Obegränsad | Claude gratis | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Proffstips:** Börja med Gemini CLI (180K gratis/månad) + iFlow (obegränsat gratis) combo = $0 kostnad! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Användningsfall +## 🎯 Use Cases -### Fall 1: "Jag har Claude Pro-abonnemang" +### Case 1: "I have Claude Pro subscription" -**Problem:** Kvoten går ut oanvänd, hastighetsgränser under tung kodning +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Fall 2: "Jag vill ha noll kostnad" +### Case 2: "I want zero cost" -**Problem:** Har inte råd med prenumerationer, behöver pålitlig AI-kodning +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Fall 3: "Jag behöver kodning dygnet runt, inga avbrott" +### Case 3: "I need 24/7 coding, no interruptions" -**Problem:** Deadlines, har inte råd med driftstopp +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Fall 4: "Jag vill ha GRATIS AI i OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Problem:** Behöver AI-assistent i meddelandeappar, helt gratis +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Leverantörsinställningar +## 📖 Provider Setup -### 🔐 Prenumerationsleverantörer +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Proffstips:** Använd Opus för komplexa uppgifter, Sonnet för snabbhet. OmniRoute spårar kvot per modell! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (GRATIS 180K/månad!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,7 +152,7 @@ Models: gc/gemini-2.5-pro ``` -**Bäst värde:** Enorma gratis nivå! Använd detta före betalda nivåer. +**Best Value:** Huge free tier! Use this before paid tiers. #### GitHub Copilot @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Billiga leverantörer +### 💰 Cheap Providers -#### GLM-4.7 (Daglig återställning, $0,6/1M) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Registrera dig: [Zhipu AI](https://open.bigmodel.cn/) -2. Hämta API-nyckel från Coding Plan -3. Instrumentpanel → Lägg till API-nyckel: Leverantör: `glm`, API-nyckel: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Användning:** `glm/glm-4.7` — **Proffstips:** Coding Plan erbjuder 3× kvot till 1/7 kostnad! Återställ dagligen 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 timmars återställning, $0,20/1M) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Registrera dig: [MiniMax](https://www.minimax.io/) -2. Hämta API-nyckel → Dashboard → Lägg till API-nyckel +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Använd:** `minimax/MiniMax-M2.1` — **Proffstips:** Billigaste alternativet för långa sammanhang (1M tokens)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/månad platt) +#### Kimi K2 ($9/month flat) -1. Prenumerera: [Moonshot AI](https://platform.moonshot.ai/) -2. Hämta API-nyckel → Dashboard → Lägg till API-nyckel +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Användning:** `kimi/kimi-latest` — **Proffstips:** Fast $9/månad för 10 miljoner tokens = $0,90/1 miljon effektiv kostnad! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 GRATIS leverantörer +### 🆓 FREE Providers -#### iFlow (8 GRATIS modeller) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 GRATIS modeller) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -221,7 +221,7 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 ## 🎨 Combos -### Exempel 1: Maximera prenumeration → Billig backup +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Exempel 2: Endast gratis (noll kostnad) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI-integration +## 🔧 CLI Integration -### Markör IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -262,7 +262,7 @@ Settings → Models → Advanced: ### Claude Code -Redigera `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Redigera `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Redigera `~/.openclaw/openclaw.json`: } ``` -**Eller använd Dashboard:** CLI Tools → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Fortsätt / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Implementering +## 🚀 Deployment -### VPS-distribution +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### Hamnarbetare +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -För värdintegrerat läge med CLI-binärer, se Docker-sektionen i huvuddokumenten. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Miljövariabler +### Environment Variables -| Variabel | Standard | Beskrivning | -| --------------------- | ------------------------------------ | ------------------------------------------------------ | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT-signeringshemlighet (**förändring i produktion**) | -| `INITIAL_PASSWORD` | `123456` | Första inloggningslösenordet | -| `DATA_DIR` | `~/.omniroute` | Datakatalog (db, användning, loggar) | -| `PORT` | ram standard | Serviceport (`20128` i exempel) | -| `HOSTNAME` | ram standard | Bind värd (Docker har som standard `0.0.0.0`) | -| `NODE_ENV` | runtime default | Ställ in `production` för distribution | -| `BASE_URL` | `http://localhost:20128` | Intern bas-URL på serversidan | -| `CLOUD_URL` | `https://omniroute.dev` | Bas-URL för molnsynkroniseringsslutpunkt | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC-hemlighet för genererade API-nycklar | -| `REQUIRE_API_KEY` | `false` | Framtvinga Bearer API-nyckel på `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Aktiverar förfrågnings-/svarsloggar | -| `AUTH_COOKIE_SECURE` | `false` | Tvinga `Secure` auth-cookie (bakom HTTPS omvänd proxy) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -För den fullständiga referensen till miljövariabeln, se [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Tillgängliga modeller +## 📊 Available Models
-Visa alla tillgängliga modeller +View all available models **Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — $0,6/1M: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $0,2/1M: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,7 +460,7 @@ För den fullständiga referensen till miljövariabeln, se [README](../README.md **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Förvirring (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` **Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` @@ -409,7 +468,7 @@ För den fullständiga referensen till miljövariabeln, se [README](../README.md **Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**Kohere (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -417,11 +476,11 @@ För den fullständiga referensen till miljövariabeln, se [README](../README.md --- -## 🧩 Avancerade funktioner +## 🧩 Advanced Features -### Anpassade modeller +### Custom Models -Lägg till valfritt modell-ID till valfri leverantör utan att vänta på en appuppdatering: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Eller använd Dashboard: **Leverantörer → [Leverantör] → Anpassade modeller**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Dedikerade leverantörsrutter +### Dedicated Provider Routes -Ruttförfrågningar direkt till en specifik leverantör med modellvalidering: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Providerprefixet läggs till automatiskt om det saknas. Omatchade modeller returnerar `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Nätverksproxykonfiguration +### Network Proxy Configuration ```bash # Set global proxy @@ -463,7 +522,7 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Tillrang:** Nyckelspecifik → Kombinationsspecifik → Leverantörsspecifik → Global → Miljö. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. ### Model Catalog API @@ -471,68 +530,68 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ curl http://localhost:20128/api/models/catalog ``` -Returnerar modeller grupperade efter leverantör med typer (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). ### Cloud Sync -- Synkronisera leverantörer, kombinationer och inställningar mellan enheter -- Automatisk bakgrundssynkronisering med timeout + felsnabb -- Föredrar serversidan `BASE_URL`/`CLOUD_URL` i produktion +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (fas 9) +### LLM Gateway Intelligence (Phase 9) -- **Semantisk cache** — Autocachar icke-strömmande, temperatur=0 svar (förbikoppla med `X-OmniRoute-No-Cache: true`) -- **Begär idempotens** — Avduplicerar förfrågningar inom 5s via `Idempotency-Key` eller `X-Request-Id` header -- **Förloppsspårning** — Opt-in SSE `event: progress`-händelser via `X-OmniRoute-Progress: true` header +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Översättarlekplats +### Translator Playground -Åtkomst via **Dashboard → Översättare**. Felsöka och visualisera hur OmniRoute översätter API-förfrågningar mellan leverantörer. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Läge | Syfte | -| ---------------- | ------------------------------------------------------------------------------------------- | -| **Lekplats** | Välj käll-/målformat, klistra in en begäran och se den översatta utdata direkt | -| **Chatttestare** | Skicka livechattmeddelanden via proxyn och inspektera hela begäran/svarscykeln | -| **Testbänk** | Kör batchtester över flera formatkombinationer för att verifiera översättningens korrekthet | -| **Live Monitor** | Se översättningar i realtid när förfrågningar flödar genom proxyn | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Användningsfall:** +**Use cases:** -- Felsök varför en specifik kombination av klient/leverantör misslyckas -- Verifiera att tanketaggar, verktygsanrop och systemuppmaningar översätts korrekt -- Jämför formatskillnader mellan OpenAI, Claude, Gemini och Responses API-format +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Routingstrategier +### Routing Strategies -Konfigurera via **Dashboard → Inställningar → Routing**. +Configure via **Dashboard → Settings → Routing**. -| Strategi | Beskrivning | -| ------------------------------ | -------------------------------------------------------------------------------------------------------------- | -| **Fyll först** | Använder konton i prioritetsordning – primärt konto hanterar alla förfrågningar tills det inte är tillgängligt | -| **Round Robin** | Går igenom alla konton med en konfigurerbar sticky limit (standard: 3 samtal per konto) | -| **P2C (Power of Two Choices)** | Väljer 2 slumpmässiga konton och vägar till det friskare — balanserar belastning med medvetenhet om hälsa | -| **Slumpmässig** | Väljer slumpmässigt ett konto för varje begäran med Fisher-Yates shuffle | -| **Minst använda** | Rutter till kontot med den äldsta `lastUsedAt` tidsstämpeln, fördelar trafiken jämnt | -| **Kostnadsoptimerad** | Rutter till kontot med lägst prioritetsvärde, optimerar för lägsta kostnadsleverantörer | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Modelalias med jokertecken +#### Wildcard Model Aliases -Skapa jokerteckenmönster för att mappa om modellnamn: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Jokertecken stöder `*` (alla tecken) och `?` (enkeltecken). +Wildcards support `*` (any characters) and `?` (single character). -#### Reservkedjor +#### Fallback Chains -Definiera globala reservkedjor som gäller för alla förfrågningar: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Motståndskraft och effektbrytare +### Resilience & Circuit Breakers -Konfigurera via **Dashboard → Inställningar → Resilience**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute implementerar motståndskraft på leverantörsnivå med fyra komponenter: +OmniRoute implements provider-level resilience with four components: -1. **Provider Profiles** — Konfiguration per leverantör för: - - Feltröskel (hur många fel före öppning) - - Nedkylningstid - - Känslighet för detektering av hastighetsgräns - - Exponentiell backoff-parametrar +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Redigerbara hastighetsgränser** — Standardinställningar på systemnivå som kan konfigureras i instrumentpanelen: - - **Requests Per Minute (RPM)** — Maximalt antal förfrågningar per minut och konto - - **Minsta tid mellan förfrågningar** — Minsta mellanrum i millisekunder mellan förfrågningar - - **Max samtidiga förfrågningar** — Maximalt antal samtidiga förfrågningar per konto - - Klicka på **Redigera** för att ändra och sedan på **Spara** eller **Avbryt**. Värden kvarstår via resilience API. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** — Spårar fel per leverantör och öppnar automatiskt kretsen när ett tröskelvärde nås: - - **STÄNGD** (frisk) — Begäran flyter normalt - - **ÖPPEN** — Leverantören är tillfälligt blockerad efter upprepade fel - - **HALF_OPEN** — Testar om leverantören har återhämtat sig +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Policy & Locked Identifiers** — Visar strömbrytarens status och låsta identifierare med tvångsupplåsning. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Rate Limit Auto-Detection** — Övervakar `429` och `Retry-After` rubriker för att proaktivt undvika att nå leverantörshastighetsgränser. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Proffstips:** Använd knappen **Återställ alla** för att rensa alla strömbrytare och nedkylningar när en leverantör återhämtar sig efter ett avbrott. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Databasexport/import +### Database Export / Import -Hantera säkerhetskopiering av databas i **Dashboard → Inställningar → System och lagring**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Åtgärd | Beskrivning | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Exportera databas** | Laddar ned den aktuella SQLite-databasen som en `.sqlite`-fil | -| **Exportera alla (.tar.gz)** | Laddar ner ett fullständigt säkerhetskopieringsarkiv inklusive: databas, inställningar, kombinationer, leverantörsanslutningar (inga referenser), API-nyckelmetadata | -| **Importera databas** | Ladda upp en `.sqlite` fil för att ersätta den aktuella databasen. En säkerhetskopia före import skapas automatiskt | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Importvalidering:** Den importerade filen är validerad för integritet (SQLite pragmakontroll), obligatoriska tabeller (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) och storlek (max 100 MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Användningsfall:** +**Use Cases:** -- Migrera OmniRoute mellan maskiner -- Skapa externa säkerhetskopior för katastrofåterställning -- Dela konfigurationer mellan teammedlemmar (exportera alla → dela arkiv) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Inställningar Dashboard +### Settings Dashboard -Inställningssidan är organiserad i 5 flikar för enkel navigering: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Innehåll | -| ------------- | ----------------------------------------------------------------------------------------------------------- | -| **Säkerhet** | Inställningar för inloggning/lösenord, IP-åtkomstkontroll, API-auth för `/models` och leverantörsblockering | -| **Ruttning** | Global routingstrategi (6 alternativ), jokerteckenmodellalias, reservkedjor, kombinationsstandarder | -| **Resiliens** | Leverantörsprofiler, redigerbara hastighetsgränser, strömbrytarstatus, policyer och låsta identifierare | -| **AI** | Tänkande budgetkonfiguration, global systempromptinjektion, promptcachestatistik | -| **Avancerat** | Global proxykonfiguration (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Kostnader och budgethantering +### Costs & Budget Management -Åtkomst via **Dashboard → Kostnader**. +Access via **Dashboard → Costs**. -| Tab | Syfte | -| ---------- | ---------------------------------------------------------------------------------------------------- | -| **Budget** | Ställ in utgiftsgränser per API-nyckel med dagliga/veckovisa/månatliga budgetar och realtidsspårning | -| **Priser** | Visa och redigera modellprisposter — kostnad per 1000 in-/utdata-tokens per leverantör | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Kostnadsspårning:** Varje begäran loggar tokenanvändning och beräknar kostnaden med hjälp av pristabellen. Visa uppdelningar i **Dashboard → Användning** efter leverantör, modell och API-nyckel. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Ljudtranskription +### Audio Transcription -OmniRoute stöder ljudtranskription via den OpenAI-kompatibla slutpunkten: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Tillgängliga leverantörer: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Ljudformat som stöds: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Kombinerade balanseringsstrategier +### Combo Balancing Strategies -Konfigurera balansering per kombination i **Dashboard → Kombinationer → Skapa/Redigera → Strategi**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Strategi | Beskrivning | -| --------------------- | -------------------------------------------------------------------------------------- | -| **Round-Robin** | Roterar genom modeller sekventiellt | -| **Prioritet** | Försöker alltid den första modellen; faller tillbaka endast på fel | -| **Slumpmässig** | Väljer en slumpmässig modell från kombinationen för varje begäran | -| **Viktad** | Rutter proportionellt baserade på tilldelade vikter per modell | -| **Minst använda** | Rutter till modellen med de minsta senaste förfrågningarna (använder kombinationsmått) | -| **Kostnadsoptimerad** | Rutter till den billigaste tillgängliga modellen (använder pristabell) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Globala kombinationsstandarder kan ställas in i **Dashboard → Inställningar → Routing → Combo Defaults**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- ### Health Dashboard -Åtkomst via **Dashboard → Hälsa**. Systemhälsoöversikt i realtid med 6 kort: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Kort | Vad den visar | -| -------------------- | ------------------------------------------------------------------ | -| **Systemstatus** | Drifttid, version, minnesanvändning, datakatalog | -| **Providers hälsa** | Tillstånd för strömbrytare per leverantör (stängd/öppen/halvöppen) | -| **Taxegränser** | Aktiva nedkylningar per konto med återstående tid | -| **Aktiva låsningar** | Leverantörer tillfälligt blockerade av lockoutpolicyn | -| **Signaturcache** | Dedupliceringscachestatistik (aktiva nycklar, träffhastighet) | -| **Latens-telemetri** | p50/p95/p99 latensaggregation per leverantör | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Proffstips:** Hälsosidan uppdateras automatiskt var tionde sekund. Använd strömbrytarkortet för att identifiera vilka leverantörer som har problem. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/th/API_REFERENCE.md b/docs/i18n/th/API_REFERENCE.md index e1763524ef..b795722c11 100644 --- a/docs/i18n/th/API_REFERENCE.md +++ b/docs/i18n/th/API_REFERENCE.md @@ -1,12 +1,12 @@ -# การอ้างอิง API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -ข้อมูลอ้างอิงที่สมบูรณ์สำหรับตำแหน่งข้อมูล OmniRoute API ทั้งหมด +Complete reference for all OmniRoute API endpoints. --- -## สารบัญ +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## เสร็จสิ้นการแชท +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### ส่วนหัวที่กำหนดเอง +### Custom Headers -| ส่วนหัว | ทิศทาง | คำอธิบาย | -| ------------------------ | ------- | ------------------------------------------- | -| `X-OmniRoute-No-Cache` | ขอ | ตั้งค่าเป็น `true` เพื่อข้ามแคช | -| `X-OmniRoute-Progress` | ขอ | ตั้งค่าเป็น `true` สำหรับกิจกรรมความคืบหน้า | -| `Idempotency-Key` | ขอ | ปุ่ม Dedup (หน้าต่าง 5s) | -| `X-Request-Id` | ขอ | คีย์สำรองสำรอง | -| `X-OmniRoute-Cache` | ตอบกลับ | `HIT` หรือ `MISS` (ไม่ใช่สตรีมมิ่ง) | -| `X-OmniRoute-Idempotent` | ตอบกลับ | `true` หากขจัดข้อมูลซ้ำซ้อน | -| `X-OmniRoute-Progress` | ตอบกลับ | `enabled` หากติดตามความคืบหน้าบน | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## การฝัง +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -ผู้ให้บริการที่มีอยู่: Nebius, OpenAI, Mistral, Together AI, ดอกไม้ไฟ, NVIDIA +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## การสร้างภาพ +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -ผู้ให้บริการที่มีอยู่: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## รายการรุ่น +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## จุดสิ้นสุดความเข้ากันได้ +## Compatibility Endpoints -| วิธีการ | เส้นทาง | รูปแบบ | -| ------- | --------------------------- | --------------------- | -| โพสต์ | `/v1/chat/completions` | OpenAI | -| โพสต์ | `/v1/messages` | มานุษยวิทยา | -| โพสต์ | `/v1/responses` | การตอบสนองของ OpenAI | -| โพสต์ | `/v1/embeddings` | OpenAI | -| โพสต์ | `/v1/images/generations` | OpenAI | -| รับ | `/v1/models` | OpenAI | -| โพสต์ | `/v1/messages/count_tokens` | มานุษยวิทยา | -| รับ | `/v1beta/models` | ราศีเมถุน | -| โพสต์ | `/v1beta/models/{...path}` | ราศีเมถุนสร้างเนื้อหา | -| โพสต์ | `/v1/api/chat` | โอลามา | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### เส้นทางของผู้ให้บริการเฉพาะ +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -คำนำหน้าผู้ให้บริการจะถูกเพิ่มอัตโนมัติหากไม่มี โมเดลที่ไม่ตรงกันส่งคืน `400` +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## แคชความหมาย +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -ตัวอย่างการตอบกลับ: +Response example: ```json { @@ -162,154 +162,164 @@ DELETE /api/cache --- -## แดชบอร์ดและการจัดการ +## Dashboard & Management -### การรับรองความถูกต้อง +### Authentication -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| ----------------------------- | ------- | ---------------------- | -| `/api/auth/login` | โพสต์ | เข้าสู่ระบบ | -| `/api/auth/logout` | โพสต์ | ออกจากระบบ | -| `/api/settings/require-login` | รับ/ใส่ | ต้องสลับการเข้าสู่ระบบ | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### การจัดการผู้ให้บริการ +### Provider Management -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| ---------------------------- | ------------ | ------------------------------ | -| `/api/providers` | รับ/โพสต์ | รายชื่อ / สร้างผู้ให้บริการ | -| `/api/providers/[id]` | รับ/วาง/ลบ | จัดการผู้ให้บริการ | -| `/api/providers/[id]/test` | โพสต์ | การเชื่อมต่อผู้ให้บริการทดสอบ | -| `/api/providers/[id]/models` | รับ | รายชื่อรุ่นของผู้ให้บริการ | -| `/api/providers/validate` | โพสต์ | ตรวจสอบการกำหนดค่าผู้ให้บริการ | -| `/api/provider-nodes*` | ต่างๆ | การจัดการโหนดผู้ให้บริการ | -| `/api/provider-models` | รับ/โพสต์/ลบ | โมเดลที่กำหนดเอง | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### กระแส OAuth +### OAuth Flows -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | +| Endpoint | Method | Description | | -------------------------------- | ------- | ----------------------- | -| `/api/oauth/[provider]/[action]` | ต่างๆ | OAuth เฉพาะผู้ให้บริการ | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### การกำหนดเส้นทางและการกำหนดค่า +### Routing & Config -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| --------------------- | --------- | ------------------------------- | -| `/api/models/alias` | รับ/โพสต์ | นามแฝงโมเดล | -| `/api/models/catalog` | รับ | ทุกรุ่นตามผู้ให้บริการ + ประเภท | -| `/api/combos*` | ต่างๆ | การจัดการคำสั่งผสม | -| `/api/keys*` | ต่างๆ | การจัดการคีย์ API | -| `/api/pricing` | รับ | ราคารุ่น | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### การใช้งานและการวิเคราะห์ +### Usage & Analytics -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| --------------------------- | ------- | ------------------------ | -| `/api/usage/history` | รับ | ประวัติการใช้งาน | -| `/api/usage/logs` | รับ | บันทึกการใช้งาน | -| `/api/usage/request-logs` | รับ | บันทึกระดับคำขอ | -| `/api/usage/[connectionId]` | รับ | การใช้งานต่อการเชื่อมต่อ | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### การตั้งค่า +### Settings -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| ------------------------------- | ------- | ------------------------------- | -| `/api/settings` | รับ/ใส่ | การตั้งค่าทั่วไป | -| `/api/settings/proxy` | รับ/ใส่ | การกำหนดค่าพร็อกซีเครือข่าย | -| `/api/settings/proxy/test` | โพสต์ | ทดสอบการเชื่อมต่อพร็อกซี | -| `/api/settings/ip-filter` | รับ/ใส่ | รายการ IP ที่อนุญาต/รายการบล็อก | -| `/api/settings/thinking-budget` | รับ/ใส่ | งบประมาณโทเค็นการใช้เหตุผล | -| `/api/settings/system-prompt` | รับ/ใส่ | พร้อมท์ระบบโกลบอล | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### การตรวจสอบ +### Monitoring -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| ------------------------ | ------- | ---------------------------- | -| `/api/sessions` | รับ | การติดตามเซสชันที่ใช้งานอยู่ | -| `/api/rate-limits` | รับ | ขีดจำกัดอัตราต่อบัญชี | -| `/api/monitoring/health` | รับ | ตรวจสุขภาพ | -| `/api/cache` | รับ/ลบ | สถิติแคช / ล้าง | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### สำรองและส่งออก/นำเข้า +### Backup & Export/Import -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| --------------------------- | ------- | ------------------------------------------- | -| `/api/db-backups` | รับ | แสดงรายการข้อมูลสำรองที่มีอยู่ | -| `/api/db-backups` | ใส่ | สร้างการสำรองข้อมูลด้วยตนเอง | -| `/api/db-backups` | โพสต์ | กู้คืนจากข้อมูลสำรองเฉพาะ | -| `/api/db-backups/export` | รับ | ดาวน์โหลดฐานข้อมูลเป็นไฟล์ .sqlite | -| `/api/db-backups/import` | โพสต์ | อัปโหลดไฟล์ .sqlite เพื่อแทนที่ฐานข้อมูล | -| `/api/db-backups/exportAll` | รับ | ดาวน์โหลดข้อมูลสำรองแบบเต็มเป็นไฟล์ .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### คลาวด์ซิงค์ +### Cloud Sync -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| ---------------------- | ------- | ------------------------- | -| `/api/sync/cloud` | ต่างๆ | การดำเนินการซิงค์บนคลาวด์ | -| `/api/sync/initialize` | โพสต์ | เริ่มต้นการซิงค์ | -| `/api/cloud/*` | ต่างๆ | การจัดการคลาวด์ | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### เครื่องมือ CLI +### CLI Tools -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| ---------------------------------- | ------- | ------------------ | -| `/api/cli-tools/claude-settings` | รับ | สถานะ Claude CLI | -| `/api/cli-tools/codex-settings` | รับ | สถานะ Codex CLI | -| `/api/cli-tools/droid-settings` | รับ | สถานะ Droid CLI | -| `/api/cli-tools/openclaw-settings` | รับ | สถานะ OpenClaw CLI | -| `/api/cli-tools/runtime/[toolId]` | รับ | รันไทม์ CLI ทั่วไป | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -การตอบกลับของ CLI ได้แก่: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason` +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### ความยืดหยุ่นและขีดจำกัดอัตรา +### ACP Agents -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | | ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | รับ/ใส่ | รับ/อัปเดตโปรไฟล์ความยืดหยุ่น | -| `/api/resilience/reset` | โพสต์ | รีเซ็ตเบรกเกอร์วงจร | -| `/api/rate-limits` | รับ | สถานะขีดจำกัดอัตราต่อบัญชี | -| `/api/rate-limit` | รับ | การกำหนดค่าขีดจำกัดอัตราทั่วโลก | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -### เอวาลส์ +### Evals -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| ------------ | --------- | --------------------------------------- | -| `/api/evals` | รับ/โพสต์ | แสดงรายการชุด eval / ดำเนินการประเมินผล | +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -### นโยบาย +### Policies -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| --------------- | ------------ | --------------------------- | -| `/api/policies` | รับ/โพสต์/ลบ | จัดการนโยบายการกำหนดเส้นทาง | +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -### การปฏิบัติตาม +### Compliance -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| --------------------------- | ------- | ------------------------------------------------- | -| `/api/compliance/audit-log` | รับ | บันทึกการตรวจสอบการปฏิบัติตามข้อกำหนด (N สุดท้าย) | +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### v1beta (เข้ากันได้กับราศีเมถุน) +### v1beta (Gemini-Compatible) -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| -------------------------- | ------- | ----------------------------------- | -| `/v1beta/models` | รับ | รายการรุ่นในรูปแบบราศีเมถุน | -| `/v1beta/models/{...path}` | โพสต์ | ราศีเมถุน `generateContent` ปลายทาง | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -ตำแหน่งข้อมูลเหล่านี้สะท้อนรูปแบบ API ของ Gemini สำหรับไคลเอนต์ที่คาดหวังความเข้ากันได้ของ Gemini SDK ดั้งเดิม +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. -### API ภายใน / ระบบ +### Internal / System APIs -| จุดสิ้นสุด | วิธีการ | คำอธิบาย | -| --------------- | ------- | ------------------------------------------------------ | -| `/api/init` | รับ | การตรวจสอบการเริ่มต้นแอปพลิเคชัน (ใช้ในการรันครั้งแรก) | -| `/api/tags` | รับ | แท็กโมเดลที่เข้ากันได้กับ Ollama (สำหรับลูกค้า Ollama) | -| `/api/restart` | โพสต์ | ทริกเกอร์การรีสตาร์ทเซิร์ฟเวอร์อย่างสง่างาม | -| `/api/shutdown` | โพสต์ | ทริกเกอร์การปิดระบบเซิร์ฟเวอร์อย่างสง่างาม | +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | -> **หมายเหตุ:** ตำแหน่งข้อมูลเหล่านี้ถูกใช้ภายในโดยระบบหรือเพื่อความเข้ากันได้กับไคลเอ็นต์ Ollama โดยทั่วไปแล้วจะไม่ถูกเรียกโดยผู้ใช้ปลายทาง +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## การถอดเสียง +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -ถอดเสียงไฟล์เสียงโดยใช้ Deepgram หรือ AssemblyAI +Transcribe audio files using Deepgram or AssemblyAI. -**คำขอ:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**คำตอบ:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**ผู้ให้บริการที่รองรับ:** `deepgram/nova-3`, `assemblyai/best` +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**รูปแบบที่รองรับ:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## ความเข้ากันได้ของ Ollama +## Ollama Compatibility -สำหรับลูกค้าที่ใช้รูปแบบ API ของ Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -คำขอจะได้รับการแปลโดยอัตโนมัติระหว่าง Ollama และรูปแบบภายใน +Requests are automatically translated between Ollama and internal formats. --- -## มาตรระยะไกล +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**คำตอบ:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## งบประมาณ +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## รุ่นที่มีจำหน่าย +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## คำขอดำเนินการ +## Request Processing -1. ลูกค้าส่งคำขอไปที่ `/v1/*` -2. ตัวจัดการเส้นทางเรียก `handleChat`, `handleEmbedding`, `handleAudioTranscription` หรือ `handleImageGeneration` -3. โมเดลได้รับการแก้ไขแล้ว (ผู้ให้บริการโดยตรง/โมเดลหรือนามแฝง/คอมโบ) -4. ข้อมูลรับรองที่เลือกจากฐานข้อมูลท้องถิ่นพร้อมการกรองความพร้อมใช้งานของบัญชี -5. สำหรับการแชท: `handleChatCore` — การตรวจจับรูปแบบ การแปล การตรวจสอบแคช การตรวจสอบค่าเดิม -6. ผู้ดำเนินการของผู้ให้บริการส่งคำขออัปสตรีม -7. การตอบสนองถูกแปลกลับเป็นรูปแบบไคลเอนต์ (แชท) หรือส่งคืนตามสภาพ (การฝัง/รูปภาพ/เสียง) -8. บันทึกการใช้งาน/การบันทึก -9. การใช้ทางเลือกสำรองจะมีผลกับข้อผิดพลาดตามกฎคอมโบ +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -การอ้างอิงสถาปัตยกรรมแบบเต็ม: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## การรับรองความถูกต้อง +## Authentication -- เส้นทางแดชบอร์ด (`/dashboard/*`) ใช้คุกกี้ `auth_token` -- การเข้าสู่ระบบใช้แฮชรหัสผ่านที่บันทึกไว้ สำรองไปที่ `INITIAL_PASSWORD` -- `requireLogin` สลับได้ผ่าน `/api/settings/require-login` -- เส้นทาง `/v1/*` เป็นทางเลือกที่ต้องใช้คีย์ Bearer API เมื่อ `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/th/ARCHITECTURE.md b/docs/i18n/th/ARCHITECTURE.md index af79d406a4..258d62df53 100644 --- a/docs/i18n/th/ARCHITECTURE.md +++ b/docs/i18n/th/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# สถาปัตยกรรม OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_อัพเดตล่าสุด: 2026-02-18_ +_Last updated: 2026-03-04_ -## บทสรุปผู้บริหาร +## Executive Summary -OmniRoute เป็นเกตเวย์การกำหนดเส้นทาง AI ในพื้นที่และแดชบอร์ดที่สร้างขึ้นบน Next.js -โดยให้จุดสิ้นสุดที่เข้ากันได้กับ OpenAI จุดเดียว (`/v1/*`) และกำหนดเส้นทางการรับส่งข้อมูลผ่านผู้ให้บริการอัปสตรีมหลายรายพร้อมการแปล ทางเลือกสำรอง การรีเฟรชโทเค็น และการติดตามการใช้งาน +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -ความสามารถหลัก: +Core capabilities: -- พื้นผิว API ที่เข้ากันได้กับ OpenAI สำหรับ CLI/เครื่องมือ (ผู้ให้บริการ 28 ราย) -- การแปลคำขอ/ตอบกลับในรูปแบบต่างๆ ของผู้ให้บริการ -- ทางเลือกคำสั่งผสมโมเดล (ลำดับหลายรุ่น) -- ทางเลือกระดับบัญชี (หลายบัญชีต่อผู้ให้บริการ) -- การจัดการการเชื่อมต่อผู้ให้บริการ OAuth + API-key -- การสร้างการฝังผ่าน `/v1/embeddings` (ผู้ให้บริการ 6 ราย, 9 โมเดล) -- การสร้างภาพผ่าน `/v1/images/generations` (ผู้ให้บริการ 4 ราย, 9 รุ่น) -- คิดว่าการแยกวิเคราะห์แท็ก (`...`) สำหรับโมเดลการให้เหตุผล -- การตอบสนองการฆ่าเชื้อสำหรับความเข้ากันได้ของ OpenAI SDK ที่เข้มงวด -- การปรับบทบาทให้เป็นมาตรฐาน (ผู้พัฒนา → ระบบ, ระบบ → ผู้ใช้) เพื่อความเข้ากันได้ระหว่างผู้ให้บริการ -- การแปลงเอาต์พุตที่มีโครงสร้าง (json_schema → Gemini responseSchema) -- ความคงอยู่ในท้องถิ่นสำหรับผู้ให้บริการ คีย์ นามแฝง คอมโบ การตั้งค่า การกำหนดราคา -- การติดตามการใช้งาน/ต้นทุน และขอบันทึก -- ตัวเลือกการซิงค์บนคลาวด์สำหรับการซิงค์หลายอุปกรณ์/สถานะ -- รายการที่อนุญาต/รายการบล็อก IP สำหรับการควบคุมการเข้าถึง API -- คิดการจัดการงบประมาณ (ส่งผ่าน/อัตโนมัติ/กำหนดเอง/ปรับเปลี่ยน) -- ระบบฉีดพร้อมท์ทั่วโลก -- การติดตามเซสชันและการพิมพ์ลายนิ้วมือ -- การจำกัดอัตราการปรับปรุงต่อบัญชีด้วยโปรไฟล์เฉพาะของผู้ให้บริการ -- รูปแบบเซอร์กิตเบรกเกอร์เพื่อความยืดหยุ่นของผู้ให้บริการ -- ป้องกันฝูงฟ้าผ่าพร้อมระบบล็อค mutex -- แคชการขจัดข้อมูลซ้ำซ้อนของคำขอตามลายเซ็น -- เลเยอร์โดเมน: ความพร้อมใช้งานของโมเดล กฎต้นทุน นโยบายทางเลือก นโยบายการล็อก -- การคงอยู่ของสถานะโดเมน (แคชการเขียนผ่าน SQLite สำหรับทางเลือกสำรอง งบประมาณ การล็อคเอาต์ เซอร์กิตเบรกเกอร์) -- กลไกนโยบายสำหรับการประเมินคำขอแบบรวมศูนย์ (ล็อค → งบประมาณ → ทางเลือก) -- ขอการตรวจวัดทางไกลด้วยการรวมเวลาแฝง p50/p95/p99 -- Correlation ID (X-Request-Id) สำหรับการติดตามจากต้นทางถึงปลายทาง -- การบันทึกการตรวจสอบการปฏิบัติตามข้อกำหนดโดยเลือกไม่ใช้ต่อคีย์ API -- กรอบการประเมินสำหรับการประกันคุณภาพ LLM -- แดชบอร์ด UI ความยืดหยุ่นพร้อมสถานะเบรกเกอร์แบบเรียลไทม์ -- ผู้ให้บริการ OAuth แบบโมดูลาร์ (12 โมดูลแต่ละโมดูลภายใต้ `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -โมเดลรันไทม์หลัก: +Primary runtime model: -- เส้นทางแอป Next.js ภายใต้ `src/app/api/*` ใช้ทั้ง API แดชบอร์ดและ API ที่เข้ากันได้ -- SSE/แกนการกำหนดเส้นทางที่ใช้ร่วมกันใน `src/sse/*` + `open-sse/*` จัดการการดำเนินการของผู้ให้บริการ การแปล การสตรีม ทางเลือกสำรอง และการใช้งาน +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## ขอบเขตและขอบเขต +## Scope and Boundaries -### ในขอบเขต +### In Scope -- รันไทม์เกตเวย์ท้องถิ่น -- API การจัดการแดชบอร์ด -- การรับรองความถูกต้องของผู้ให้บริการและการรีเฟรชโทเค็น -- ขอการแปลและการสตรีม SSE -- สภาพท้องถิ่น + ความคงทนในการใช้งาน -- การประสานการซิงค์บนคลาวด์เสริม +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### อยู่นอกขอบเขต +### Out of Scope -- การใช้งานบริการคลาวด์เบื้องหลัง `NEXT_PUBLIC_CLOUD_URL` -- SLA ของผู้ให้บริการ/ระนาบควบคุมอยู่นอกกระบวนการท้องถิ่น -- ไบนารี CLI ภายนอกเอง (Claude CLI, Codex CLI ฯลฯ ) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## บริบทของระบบระดับสูง +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## ส่วนประกอบรันไทม์หลัก +## Core Runtime Components -## 1) API และเลเยอร์การกำหนดเส้นทาง (เส้นทางแอป Next.js) +## 1) API and Routing Layer (Next.js App Routes) -ไดเรกทอรีหลัก: +Main directories: -- `src/app/api/v1/*` และ `src/app/api/v1beta/*` สำหรับ API ที่เข้ากันได้ -- `src/app/api/*` สำหรับ API การจัดการ/การกำหนดค่า -- เขียนใหม่ครั้งต่อไปใน `next.config.mjs` แผนที่ `/v1/*` ถึง `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -เส้นทางความเข้ากันได้ที่สำคัญ: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — รวมโมเดลที่กำหนดเองด้วย `custom: true` -- `src/app/api/v1/embeddings/route.ts` — การสร้างการฝัง (ผู้ให้บริการ 6 ราย) -- `src/app/api/v1/images/generations/route.ts` — การสร้างภาพ (ผู้ให้บริการ 4+ รายรวม Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — แชทเฉพาะต่อผู้ให้บริการ -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — การฝังต่อผู้ให้บริการโดยเฉพาะ -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — อิมเมจต่อผู้ให้บริการโดยเฉพาะ +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -โดเมนการจัดการ: +Management domains: -- การรับรองความถูกต้อง/การตั้งค่า: `src/app/api/auth/*`, `src/app/api/settings/*` -- ผู้ให้บริการ/การเชื่อมต่อ: `src/app/api/providers*` -- โหนดผู้ให้บริการ: `src/app/api/provider-nodes*` -- โมเดลที่กำหนดเอง: `src/app/api/provider-models` (GET/POST/DELETE) -- แคตตาล็อกรุ่น: `src/app/api/models/catalog` (GET) -- การกำหนดค่าพร็อกซี: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- คีย์/นามแฝง/คอมโบ/ราคา: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- การใช้งาน: `src/app/api/usage/*` -- ซิงค์/คลาวด์: `src/app/api/sync/*`, `src/app/api/cloud/*` -- ผู้ช่วยเครื่องมือ CLI: `src/app/api/cli-tools/*` -- ตัวกรอง IP: `src/app/api/settings/ip-filter` (GET/PUT) -- งบประมาณการคิด: `src/app/api/settings/thinking-budget` (GET/PUT) -- ระบบแจ้ง: `src/app/api/settings/system-prompt` (GET/PUT) -- เซสชัน: `src/app/api/sessions` (GET) -- ขีดจำกัดอัตรา: `src/app/api/rate-limits` (GET) -- ความยืดหยุ่น: `src/app/api/resilience` (GET/PATCH) — โปรไฟล์ผู้ให้บริการ, เซอร์กิตเบรกเกอร์, สถานะขีดจำกัดอัตรา -- รีเซ็ตความยืดหยุ่น: `src/app/api/resilience/reset` (POST) — รีเซ็ตเบรกเกอร์ + คูลดาวน์ -- สถิติแคช: `src/app/api/cache/stats` (GET/DELETE) -- ความพร้อมของรุ่น: `src/app/api/models/availability` (GET/POST) -- การวัดและส่งข้อมูลทางไกล: `src/app/api/telemetry/summary` (GET) -- งบประมาณ: `src/app/api/usage/budget` (GET/POST) -- เชนทางเลือก: `src/app/api/fallback/chains` (GET/POST/DELETE) -- การตรวจสอบการปฏิบัติตามข้อกำหนด: `src/app/api/compliance/audit-log` (GET) -- คะแนน: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- นโยบาย: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + แกนการแปล +## 2) SSE + Translation Core -โมดูลการไหลหลัก: +Main flow modules: -- รายการ: `src/sse/handlers/chat.ts` -- การประสานหลัก: `open-sse/handlers/chatCore.ts` -- อะแดปเตอร์การดำเนินการของผู้ให้บริการ: `open-sse/executors/*` -- รูปแบบการตรวจจับ/การกำหนดค่าผู้ให้บริการ: `open-sse/services/provider.ts` -- โมเดลแยกวิเคราะห์/แก้ไข: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- ตรรกะทางเลือกของบัญชี: `open-sse/services/accountFallback.ts` -- รีจิสทรีการแปล: `open-sse/translator/index.ts` -- การแปลงสตรีม: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- การแยกการใช้งาน/การทำให้เป็นมาตรฐาน: `open-sse/utils/usageTracking.ts` -- คิดว่าตัวแยกวิเคราะห์แท็ก: `open-sse/utils/thinkTagParser.ts` -- ตัวจัดการการฝัง: `open-sse/handlers/embeddings.ts` -- การลงทะเบียนผู้ให้บริการการฝัง: `open-sse/config/embeddingRegistry.ts` -- ตัวจัดการการสร้างอิมเมจ: `open-sse/handlers/imageGeneration.ts` -- รีจิสทรีของผู้ให้บริการอิมเมจ: `open-sse/config/imageRegistry.ts` -- การตอบสนองการฆ่าเชื้อ: `open-sse/handlers/responseSanitizer.ts` -- การทำให้บทบาทเป็นมาตรฐาน: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -บริการ (ตรรกะทางธุรกิจ): +Services (business logic): -- การเลือกบัญชี/การให้คะแนน: `open-sse/services/accountSelector.ts` -- การจัดการวงจรชีวิตบริบท: `open-sse/services/contextManager.ts` -- การบังคับใช้ตัวกรอง IP: `open-sse/services/ipFilter.ts` -- การติดตามเซสชัน: `open-sse/services/sessionManager.ts` -- ขอการขจัดข้อมูลซ้ำซ้อน: `open-sse/services/signatureCache.ts` -- ระบบพร้อมท์การฉีด: `open-sse/services/systemPrompt.ts` -- คิดการจัดการงบประมาณ: `open-sse/services/thinkingBudget.ts` -- การกำหนดเส้นทางโมเดลตัวแทน: `open-sse/services/wildcardRouter.ts` -- การจัดการขีดจำกัดอัตรา: `open-sse/services/rateLimitManager.ts` -- เบรกเกอร์: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -โมดูลเลเยอร์โดเมน: +Domain layer modules: -- รุ่นที่มีวางจำหน่าย: `src/lib/domain/modelAvailability.ts` -- กฎต้นทุน/งบประมาณ: `src/lib/domain/costRules.ts` -- นโยบายสำรอง: `src/lib/domain/fallbackPolicy.ts` -- ตัวแก้ไขคำสั่งผสม: `src/lib/domain/comboResolver.ts` -- นโยบายการล็อก: `src/lib/domain/lockoutPolicy.ts` -- กลไกนโยบาย: `src/domain/policyEngine.ts` — การล็อคแบบรวมศูนย์ → งบประมาณ → การประเมินทางเลือก -- แค็ตตาล็อกรหัสข้อผิดพลาด: `src/lib/domain/errorCodes.ts` -- รหัสคำขอ: `src/lib/domain/requestId.ts` -- หมดเวลาดึงข้อมูล: `src/lib/domain/fetchTimeout.ts` -- ขอการตรวจวัดระยะไกล: `src/lib/domain/requestTelemetry.ts` -- การปฏิบัติตามข้อกำหนด/การตรวจสอบ: `src/lib/domain/compliance/index.ts` -- นักวิ่งประเมิน: `src/lib/domain/evalRunner.ts` -- การคงอยู่ของสถานะโดเมน: `src/lib/db/domainState.ts` — SQLite CRUD สำหรับเชนสำรอง งบประมาณ ประวัติต้นทุน สถานะการล็อกเอาต์ เซอร์กิตเบรกเกอร์ +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -โมดูลผู้ให้บริการ OAuth (12 ไฟล์แต่ละไฟล์ภายใต้ `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- ดัชนีรีจิสทรี: `src/lib/oauth/providers/index.ts` -- ผู้ให้บริการส่วนบุคคล: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- กระดาษห่อแบบบาง: `src/lib/oauth/providers.ts` — ส่งออกซ้ำจากแต่ละโมดูล +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) เลเยอร์การคงอยู่ +## 3) Persistence Layer -ฐานข้อมูลสถานะหลัก: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- ไฟล์: `${DATA_DIR}/db.json` (หรือ `$XDG_CONFIG_HOME/omniroute/db.json` เมื่อตั้งค่า มิฉะนั้น `~/.omniroute/db.json`) -- เอนทิตี: providerConnections, providerNodes, modelAliases, คอมโบ, apiKeys, การตั้งค่า, การกำหนดราคา, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -ฐานข้อมูลการใช้งาน: +Usage persistence: -- `src/lib/usageDb.ts` -- ไฟล์: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- เป็นไปตามนโยบายไดเรกทอรีฐานเดียวกันกับ `localDb` (`DATA_DIR` จากนั้น `XDG_CONFIG_HOME/omniroute` เมื่อตั้งค่า) -- แบ่งออกเป็นโมดูลย่อยที่เน้น: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -ฐานข้อมูลสถานะโดเมน (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — การดำเนินการ CRUD สำหรับสถานะโดเมน -- ตาราง (สร้างใน `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- รูปแบบแคชการเขียนผ่าน: แผนที่ในหน่วยความจำเชื่อถือได้ ณ รันไทม์ การกลายพันธุ์จะถูกเขียนพร้อมกันกับ SQLite; สถานะถูกกู้คืนจาก DB เมื่อสตาร์ทขณะเย็น +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) การรับรองความถูกต้อง + พื้นผิวการรักษาความปลอดภัย +## 4) Auth + Security Surfaces -- การตรวจสอบคุกกี้แดชบอร์ด: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- การสร้าง/การตรวจสอบคีย์ API: `src/shared/utils/apiKey.ts` -- ข้อมูลลับของผู้ให้บริการยังคงอยู่ในรายการ `providerConnections` -- รองรับพร็อกซีขาออกผ่าน `open-sse/utils/proxyFetch.ts` (env vars) และ `open-sse/utils/networkProxy.ts` (กำหนดค่าได้ต่อผู้ให้บริการหรือทั่วโลก) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) การซิงค์บนคลาวด์ +## 5) Cloud Sync -- เริ่มต้นตัวกำหนดเวลา: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- งานประจำ: `src/shared/services/cloudSyncScheduler.ts` -- เส้นทางควบคุม: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## ระยะเวลาคำขอ (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + ขั้นตอนทางเลือกของบัญชี +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -การตัดสินใจทางเลือกถูกขับเคลื่อนโดย `open-sse/services/accountFallback.ts` โดยใช้รหัสสถานะและการวิเคราะห์พฤติกรรมข้อความแสดงข้อผิดพลาด +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## การเริ่มต้นใช้งาน OAuth และวงจรการรีเฟรชโทเค็น +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -การรีเฟรชระหว่างการรับส่งข้อมูลสดจะดำเนินการภายใน `open-sse/handlers/chatCore.ts` ผ่านตัวดำเนินการ `refreshCredentials()` +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## วงจรการใช้งาน Cloud Sync (เปิดใช้งาน / ซิงค์ / ปิดใช้งาน) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -การซิงค์เป็นระยะจะถูกทริกเกอร์โดย `CloudSyncScheduler` เมื่อเปิดใช้งานระบบคลาวด์ +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## แบบจำลองข้อมูลและแผนที่การจัดเก็บ +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -ไฟล์จัดเก็บข้อมูลทางกายภาพ: +Physical storage files: -- สถานะหลัก: `${DATA_DIR}/db.json` (หรือ `$XDG_CONFIG_HOME/omniroute/db.json` เมื่อตั้งค่า มิฉะนั้น `~/.omniroute/db.json`) -- สถิติการใช้งาน: `${DATA_DIR}/usage.json` -- ขอบรรทัดบันทึก: `${DATA_DIR}/log.txt` -- ตัวเลือกนักแปล/ร้องขอเซสชันการแก้ไขข้อบกพร่อง: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## โทโพโลยีการปรับใช้ +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## การทำแผนที่โมดูล (การตัดสินใจที่สำคัญ) +## Module Mapping (Decision-Critical) -### เส้นทางและโมดูล API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API ความเข้ากันได้ -- `src/app/api/v1/providers/[provider]/*`: เส้นทางเฉพาะต่อผู้ให้บริการ (แชท การฝัง รูปภาพ) -- `src/app/api/providers*`: ผู้ให้บริการ CRUD, การตรวจสอบความถูกต้อง, การทดสอบ -- `src/app/api/provider-nodes*`: การจัดการโหนดที่เข้ากันได้แบบกำหนดเอง -- `src/app/api/provider-models`: การจัดการโมเดลแบบกำหนดเอง (CRUD) -- `src/app/api/models/catalog`: API แคตตาล็อกโมเดลแบบเต็ม (ทุกประเภทจัดกลุ่มตามผู้ให้บริการ) -- `src/app/api/oauth/*`: การไหลของ OAuth/รหัสอุปกรณ์ -- `src/app/api/keys*`: วงจรการใช้งานคีย์ API ภายในเครื่อง -- `src/app/api/models/alias`: การจัดการนามแฝง -- `src/app/api/combos*`: การจัดการคอมโบทางเลือก -- `src/app/api/pricing`: แทนที่การกำหนดราคาสำหรับการคำนวณต้นทุน -- `src/app/api/settings/proxy`: การกำหนดค่าพร็อกซี (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: การทดสอบการเชื่อมต่อพร็อกซีขาออก (POST) -- `src/app/api/usage/*`: การใช้งานและบันทึก API -- `src/app/api/sync/*` + `src/app/api/cloud/*`: การซิงค์บนคลาวด์และผู้ช่วยเหลือบนคลาวด์ -- `src/app/api/cli-tools/*`: ตัวเขียน/ตัวตรวจสอบการกำหนดค่า CLI ในเครื่อง -- `src/app/api/settings/ip-filter`: รายการ IP ที่อนุญาต/รายการบล็อก (GET/PUT) -- `src/app/api/settings/thinking-budget`: คิดการกำหนดค่างบประมาณโทเค็น (GET/PUT) -- `src/app/api/settings/system-prompt`: พร้อมท์ระบบทั่วโลก (GET/PUT) -- `src/app/api/sessions`: รายการเซสชันที่ใช้งานอยู่ (GET) -- `src/app/api/rate-limits`: สถานะขีดจำกัดอัตราต่อบัญชี (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### แกนการกำหนดเส้นทางและการดำเนินการ +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: คำขอแยกวิเคราะห์ การจัดการคำสั่งผสม วนรอบการเลือกบัญชี -- `open-sse/handlers/chatCore.ts`: การแปล การดำเนินการจัดส่ง การจัดการลองใหม่/รีเฟรช การตั้งค่าสตรีม -- `open-sse/executors/*`: เครือข่ายเฉพาะผู้ให้บริการและพฤติกรรมรูปแบบ +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### รีจิสทรีการแปลและตัวแปลงรูปแบบ +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: ทะเบียนนักแปลและเรียบเรียง -- ขอนักแปล: `open-sse/translator/request/*` -- ผู้แปลคำตอบ: `open-sse/translator/response/*` -- รูปแบบค่าคงที่: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### ความคงอยู่ +### Persistence -- `src/lib/localDb.ts`: การกำหนดค่า/สถานะแบบถาวร -- `src/lib/usageDb.ts`: ประวัติการใช้งานและบันทึกคำขอแบบต่อเนื่อง +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## ความครอบคลุมของผู้ให้บริการ (รูปแบบกลยุทธ์) +## Provider Executor Coverage (Strategy Pattern) -ผู้ให้บริการแต่ละรายมีตัวดำเนินการเฉพาะที่ขยาย `BaseExecutor` (ใน `open-sse/executors/base.ts`) ซึ่งจัดเตรียมการสร้าง URL การสร้างส่วนหัว การลองอีกครั้งด้วย Exponential Backoff ฮุคการรีเฟรชข้อมูลประจำตัว และวิธีการประสาน `execute()` +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| ผู้ดำเนินการ | ผู้ให้บริการ | การจัดการพิเศษ | -| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, ความฉงนสนเท่ห์, Together, ดอกไม้ไฟ, Cerebras, Cohere, NVIDIA | URL แบบไดนามิก/การกำหนดค่าส่วนหัวต่อผู้ให้บริการ | -| `AntigravityExecutor` | Google ต้านแรงโน้มถ่วง | รหัสโปรเจ็กต์/เซสชันแบบกำหนดเอง ลองอีกครั้งหลังจากแยกวิเคราะห์ | -| `CodexExecutor` | OpenAI Codex | แทรกคำสั่งของระบบ บังคับใช้ความพยายามในการให้เหตุผล | -| `CursorExecutor` | เคอร์เซอร์ IDE | โปรโตคอล ConnectRPC, การเข้ารหัส Protobuf, ขอการลงนามผ่านเช็คซัม | -| `GithubExecutor` | นักบิน GitHub | การรีเฟรชโทเค็น Copilot ส่วนหัวการเลียนแบบ VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | รูปแบบไบนารี AWS EventStream → การแปลง SSE | -| `GeminiCLIExecutor` | ราศีเมถุน CLI | วงจรการรีเฟรชโทเค็น Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -ผู้ให้บริการรายอื่นทั้งหมด (รวมถึงโหนดที่เข้ากันได้แบบกำหนดเอง) ใช้ `DefaultExecutor` +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## เมทริกซ์ความเข้ากันได้ของผู้ให้บริการ +## Provider Compatibility Matrix -| ผู้ให้บริการ | รูปแบบ | รับรองความถูกต้อง | สตรีม | ไม่ใช่สตรีม | รีเฟรชโทเค็น | API การใช้งาน | -| ------------------- | --------------- | ---------------------- | ---------------- | ----------- | ------------ | --------------------- | -| คลอดด์ | คลอด | คีย์ API / OAuth | ✅ | ✅ | ✅ | ⚠️เฉพาะแอดมินเท่านั้น | -| ราศีเมถุน | ราศีเมถุน | คีย์ API / OAuth | ✅ | ✅ | ✅ | ⚠️ คลาวด์คอนโซล | -| ราศีเมถุน CLI | ราศีเมถุน-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ คลาวด์คอนโซล | -| ต้านแรงโน้มถ่วง | ต้านแรงโน้มถ่วง | OAuth | ✅ | ✅ | ✅ | ✅ API โควต้าเต็ม | -| OpenAI | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| โคเด็กซ์ | openai ตอบกลับ | OAuth | ✅บังคับ | ❌ | ✅ | ✅ ขีดจำกัดอัตรา | -| นักบิน GitHub | เปิดใจ | OAuth + โทเค็น Copilot | ✅ | ✅ | ✅ | ✅ สแนปชอตโควต้า | -| เคอร์เซอร์ | เคอร์เซอร์ | เช็คซัมแบบกำหนดเอง | ✅ | ✅ | ❌ | ❌ | -| คิโระ | คิโระ | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ ขีดจำกัดการใช้งาน | -| ควีน | เปิดใจ | OAuth | ✅ | ✅ | ✅ | ⚠️ตามคำขอ | -| ไอโฟลว์ | เปิดใจ | OAuth (พื้นฐาน) | ✅ | ✅ | ✅ | ⚠️ตามคำขอ | -| OpenRouter | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| GLM/คิมิ/มินิแม็กซ์ | คลอด | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| กรอค | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| xAI (โกรก) | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| มิสทรัล | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| ความฉงนสนเท่ห์ | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| ร่วมกัน AI | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| ดอกไม้ไฟ AI | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| สมอง | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| เชื่อมโยง | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | เปิดใจ | คีย์ API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## รูปแบบความครอบคลุมการแปล +## Format Translation Coverage -รูปแบบแหล่งที่มาที่ตรวจพบ ได้แก่: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -รูปแบบเป้าหมายได้แก่: +Target formats include: -- แชท / ตอบกลับ OpenAI -- คลอดด์ -- Gemini/Gemini-CLI/ซองต้านแรงโน้มถ่วง -- คิโระ -- เคอร์เซอร์ +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -การแปลใช้ **OpenAI เป็นรูปแบบฮับ** — การแปลงทั้งหมดผ่าน OpenAI เป็นตัวกลาง: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -การแปลจะถูกเลือกแบบไดนามิกตามรูปร่างเพย์โหลดต้นทางและรูปแบบเป้าหมายของผู้ให้บริการ +Translations are selected dynamically based on source payload shape and provider target format. -เลเยอร์การประมวลผลเพิ่มเติมในไปป์ไลน์การแปล: +Additional processing layers in the translation pipeline: -- **การฆ่าเชื้อการตอบสนอง** — ตัดช่องที่ไม่ได้มาตรฐานออกจากการตอบสนองในรูปแบบ OpenAI (ทั้งแบบสตรีมมิ่งและไม่ใช่สตรีมมิ่ง) เพื่อให้มั่นใจว่าสอดคล้องกับ SDK ที่เข้มงวด -- **การปรับบทบาทให้เป็นมาตรฐาน** — แปลง `developer` → `system` สำหรับเป้าหมายที่ไม่ใช่ OpenAI ผสาน `system` → `user` สำหรับโมเดลที่ปฏิเสธบทบาทของระบบ (GLM, ERNIE) -- **ลองแยกแท็ก** — แยกวิเคราะห์บล็อก `...` จากเนื้อหาลงในฟิลด์ `reasoning_content` -- **เอาต์พุตที่มีโครงสร้าง** — แปลง OpenAI `response_format.json_schema` เป็น `responseMimeType` + `responseSchema` ของ Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## จุดสิ้นสุด API ที่รองรับ +## Supported API Endpoints -| จุดสิ้นสุด | Format | ตัวจัดการ | -| -------------------------------------------------- | --------------------- | ------------------------------------------------------ | -| `POST /v1/chat/completions` | แชท OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | ข้อความของคลอดด์ | ตัวจัดการเดียวกัน (ตรวจพบอัตโนมัติ) | -| `POST /v1/responses` | การตอบสนองของ OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | การฝัง OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | รายการรุ่น | เส้นทาง API | -| `POST /v1/images/generations` | รูปภาพ OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | รายการรุ่น | เส้นทาง API | -| `POST /v1/providers/{provider}/chat/completions` | แชท OpenAI | เฉพาะต่อผู้ให้บริการพร้อมการตรวจสอบโมเดล | -| `POST /v1/providers/{provider}/embeddings` | การฝัง OpenAI | เฉพาะต่อผู้ให้บริการพร้อมการตรวจสอบโมเดล | -| `POST /v1/providers/{provider}/images/generations` | รูปภาพ OpenAI | เฉพาะต่อผู้ให้บริการพร้อมการตรวจสอบโมเดล | -| `POST /v1/messages/count_tokens` | จำนวนโทเค็นของ Claude | เส้นทาง API | -| `GET /v1/models` | รายการโมเดล OpenAI | เส้นทาง API (แชท + การฝัง + รูปภาพ + โมเดลที่กำหนดเอง) | -| `GET /api/models/catalog` | แคตตาล็อก | ทุกรุ่นจัดกลุ่มตามผู้ให้บริการ + ประเภท | -| `POST /v1beta/models/*:streamGenerateContent` | ชาวราศีเมถุนพื้นเมือง | เส้นทาง API | -| `GET/PUT/DELETE /api/settings/proxy` | การกำหนดค่าพร็อกซี | การกำหนดค่าพร็อกซีเครือข่าย | -| `POST /api/settings/proxy/test` | การเชื่อมต่อพร็อกซี | จุดสิ้นสุดการทดสอบความสมบูรณ์ของพร็อกซี/การเชื่อมต่อ | -| `GET/POST/DELETE /api/provider-models` | โมเดลที่กำหนดเอง | การจัดการโมเดลแบบกำหนดเองต่อผู้ให้บริการ | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## บายพาสตัวจัดการ +## Bypass Handler -ตัวจัดการบายพาส (`open-sse/utils/bypassHandler.ts`) สกัดกั้นคำขอ "ทิ้ง" ที่รู้จักจาก Claude CLI - การปิงอุ่นเครื่อง การแยกชื่อ และจำนวนโทเค็น - และส่งคืน **การตอบกลับปลอม** โดยไม่ต้องใช้โทเค็นของผู้ให้บริการอัปสตรีม สิ่งนี้จะถูกทริกเกอร์เฉพาะเมื่อ `User-Agent` มี `claude-cli` +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## ขอไปป์ไลน์ Logger +## Request Logger Pipeline -ตัวบันทึกคำขอ (`open-sse/utils/requestLogger.ts`) จัดเตรียมไปป์ไลน์การบันทึกการดีบัก 7 ขั้นตอน ซึ่งปิดใช้งานโดยค่าเริ่มต้น เปิดใช้งานผ่าน `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -ไฟล์ถูกเขียนไปที่ `/logs//` สำหรับแต่ละเซสชันคำขอ +Files are written to `/logs//` for each request session. -## โหมดความล้มเหลวและความยืดหยุ่น +## Failure Modes and Resilience -## 1) ความพร้อมใช้งานของบัญชี/ผู้ให้บริการ +## 1) Account/Provider Availability -- คูลดาวน์บัญชีผู้ให้บริการเกี่ยวกับข้อผิดพลาดชั่วคราว/อัตรา/การตรวจสอบสิทธิ์ -- ทางเลือกบัญชีก่อนที่จะล้มเหลวในการร้องขอ -- ทางเลือกของโมเดลคอมโบเมื่อพาธของโมเดล/ผู้ให้บริการปัจจุบันหมดลง +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) โทเค็นหมดอายุ +## 2) Token Expiry -- ตรวจสอบล่วงหน้าและรีเฟรชด้วยการลองอีกครั้งสำหรับผู้ให้บริการที่รีเฟรชได้ -- 401/403 ลองอีกครั้งหลังจากพยายามรีเฟรชในเส้นทางหลัก +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) ความปลอดภัยของสตรีม +## 3) Stream Safety -- ตัวควบคุมสตรีมที่รับรู้การตัดการเชื่อมต่อ -- สตรีมการแปลพร้อมฟลัชปลายสตรีมและการจัดการ `[DONE]` -- การประมาณการใช้งานสำรองเมื่อข้อมูลเมตาการใช้งานของผู้ให้บริการหายไป +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) การเสื่อมสภาพของ Cloud Sync +## 4) Cloud Sync Degradation -- ข้อผิดพลาดในการซิงค์ปรากฏขึ้น แต่รันไทม์ในเครื่องยังคงดำเนินต่อไป -- ตัวกำหนดตารางเวลามีตรรกะที่สามารถลองใหม่ได้ แต่การดำเนินการตามระยะเวลาในปัจจุบันจะเรียกการซิงค์แบบพยายามครั้งเดียวตามค่าเริ่มต้น +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) ความสมบูรณ์ของข้อมูล +## 5) Data Integrity -- การโยกย้าย / ซ่อมแซมรูปร่าง DB สำหรับคีย์ที่หายไป -- การป้องกันการรีเซ็ต JSON ที่เสียหายสำหรับ localDb และการใช้งานDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## ความสามารถในการสังเกตและสัญญาณการปฏิบัติงาน +## Observability and Operational Signals -แหล่งที่มาของการมองเห็นรันไทม์: +Runtime visibility sources: -- บันทึกคอนโซลจาก `src/sse/utils/logger.ts` -- รวมการใช้งานต่อคำขอใน `usage.json` -- บันทึกสถานะคำขอที่เป็นข้อความใน `log.txt` -- บันทึกคำขอ/การแปลเชิงลึกเพิ่มเติมภายใต้ `logs/` เมื่อ `ENABLE_REQUEST_LOGS=true` -- จุดสิ้นสุดการใช้งานแดชบอร์ด (`/api/usage/*`) สำหรับการใช้ UI +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## ขอบเขตที่ละเอียดอ่อนด้านความปลอดภัย +## Security-Sensitive Boundaries -- ความลับ JWT (`JWT_SECRET`) รักษาความปลอดภัยการตรวจสอบ / การลงนามคุกกี้เซสชันแดชบอร์ด -- ทางเลือกรหัสผ่านเริ่มต้น (`INITIAL_PASSWORD`, ค่าเริ่มต้น `123456`) จะต้องถูกแทนที่ในการปรับใช้จริง -- คีย์ API ความลับ HMAC (`API_KEY_SECRET`) รักษาความปลอดภัยรูปแบบคีย์ API ในเครื่องที่สร้างขึ้น -- ความลับของผู้ให้บริการ (คีย์/โทเค็น API) ยังคงอยู่ในฐานข้อมูลในเครื่องและควรได้รับการปกป้องในระดับระบบไฟล์ -- จุดสิ้นสุดการซิงค์บนคลาวด์อาศัยการตรวจสอบสิทธิ์คีย์ API + ซีแมนทิกส์รหัสเครื่อง +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## สภาพแวดล้อมและเมทริกซ์รันไทม์ +## Environment and Runtime Matrix -ตัวแปรสภาพแวดล้อมที่ใช้งานโดยโค้ด: +Environment variables actively used by code: -- แอป/การรับรองความถูกต้อง: `JWT_SECRET`, `INITIAL_PASSWORD` -- ที่เก็บข้อมูล: `DATA_DIR` -- ลักษณะการทำงานของโหนดที่เข้ากันได้: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- การแทนที่ฐานจัดเก็บข้อมูลเสริม (Linux/macOS เมื่อ `DATA_DIR` ไม่ได้ตั้งค่า): `XDG_CONFIG_HOME` -- การรักษาความปลอดภัย: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- การบันทึก: `ENABLE_REQUEST_LOGS` -- การซิงโครไนซ์/คลาวด์ URL: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- พร็อกซีขาออก: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` และรูปแบบตัวพิมพ์เล็ก -- ธงคุณลักษณะ SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- ตัวช่วยแพลตฟอร์ม/รันไทม์ (ไม่ใช่การกำหนดค่าเฉพาะแอป): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## หมายเหตุทางสถาปัตยกรรมที่เป็นที่รู้จัก +## Known Architectural Notes -1. `usageDb` และ `localDb` แชร์นโยบายไดเรกทอรีฐานเดียวกัน (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) ด้วยการย้ายไฟล์แบบเดิม -2. `/api/v1/route.ts` ส่งคืนรายการโมเดลแบบคงที่ และไม่ใช่แหล่งที่มาของโมเดลหลักที่ใช้โดย `/v1/models` -3. ตัวบันทึกคำขอเขียนส่วนหัว/เนื้อหาแบบเต็มเมื่อเปิดใช้งาน ถือว่าไดเร็กทอรีบันทึกมีความละเอียดอ่อน -4. พฤติกรรมของคลาวด์ขึ้นอยู่กับ `NEXT_PUBLIC_BASE_URL` ที่ถูกต้องและความสามารถในการเข้าถึงจุดสิ้นสุดของคลาวด์ -5. ไดเร็กทอรี `open-sse/` ได้รับการเผยแพร่เป็น `@omniroute/open-sse` **แพ็กเกจพื้นที่ทำงาน npm** ซอร์สโค้ดนำเข้าผ่าน `@omniroute/open-sse/...` (แก้ไขโดย Next.js `transpilePackages`) พาธของไฟล์ในเอกสารนี้ยังคงใช้ชื่อไดเร็กทอรี `open-sse/` เพื่อความสอดคล้องกัน -6. แผนภูมิในแดชบอร์ดใช้ **แผนภูมิใหม่** (อิงตาม SVG) สำหรับการแสดงภาพการวิเคราะห์เชิงโต้ตอบที่เข้าถึงได้ (แผนภูมิแท่งการใช้งานโมเดล ตารางแจกแจงผู้ให้บริการพร้อมอัตราความสำเร็จ) -7. การทดสอบ E2E ใช้ **นักเขียนบทละคร** (`tests/e2e/`) รันผ่าน `npm run test:e2e` การทดสอบหน่วยใช้ **ตัวดำเนินการทดสอบ Node.js** (`tests/unit/`) รันผ่าน `npm run test:plan3` ซอร์สโค้ดภายใต้ `src/` คือ **TypeScript** (`.ts`/`.tsx`); เวิร์กสเปซ `open-sse/` ยังคงเป็น JavaScript (`.js`) -8. หน้าการตั้งค่าแบ่งออกเป็น 5 แท็บ: ความปลอดภัย การกำหนดเส้นทาง (6 กลยุทธ์ระดับโลก: เติมก่อน ปัดเศษ p2c สุ่ม ใช้น้อยที่สุด ปรับต้นทุนให้เหมาะสม) ความยืดหยุ่น (จำกัดอัตราที่แก้ไขได้ เซอร์กิตเบรกเกอร์ นโยบาย) AI (การคิดงบประมาณ พรอมต์ของระบบ แคชพร้อมต์) ขั้นสูง (พร็อกซี) +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## รายการตรวจสอบการตรวจสอบการปฏิบัติงาน +## Operational Verification Checklist -- สร้างจากแหล่งที่มา: `npm run build` -- สร้างอิมเมจนักเทียบท่า: `docker build -t omniroute .` -- เริ่มบริการและตรวจสอบ: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- URL ฐานเป้าหมาย CLI ควรเป็น `http://:20128/v1` เมื่อ `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/th/CODEBASE_DOCUMENTATION.md b/docs/i18n/th/CODEBASE_DOCUMENTATION.md index c2096ce0c6..303880c198 100644 --- a/docs/i18n/th/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/th/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — เอกสาร Codebase +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> คู่มือที่ครอบคลุมและเหมาะสำหรับผู้เริ่มต้นสำหรับเราเตอร์พร็อกซี AI ของผู้ให้บริการหลายราย **omniroute** +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Omniroute คืออะไร? +## 1. What Is omniroute? -Omniroute คือ **เราเตอร์พร็อกซี** ที่อยู่ระหว่างไคลเอนต์ AI (Claude CLI, Codex, Cursor IDE ฯลฯ) และผู้ให้บริการ AI (Anthropic, Google, OpenAI, AWS, GitHub ฯลฯ) มันแก้ปัญหาใหญ่อย่างหนึ่ง: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **ไคลเอนต์ AI ต่างกันพูด "ภาษา" ที่แตกต่างกัน (รูปแบบ API) และผู้ให้บริการ AI ต่างคาดหวัง "ภาษา" ที่แตกต่างกันเช่นกัน** การแปลทุกเส้นทางระหว่างกันโดยอัตโนมัติ +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -ลองคิดดูว่าสิ่งนี้เหมือนกับนักแปลสากลขององค์การสหประชาชาติ ผู้แทนทุกคนสามารถพูดภาษาใดก็ได้ และผู้แปลจะแปลงภาษาดังกล่าวให้กับผู้แทนคนอื่นๆ +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. ภาพรวมสถาปัตยกรรม +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### หลักการสำคัญ: การแปลแบบ Hub-and-Spoke +### Core Principle: Hub-and-Spoke Translation -การแปลทุกรูปแบบผ่าน **รูปแบบ OpenAI เป็นศูนย์กลาง**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -ซึ่งหมายความว่าคุณต้องการเพียง **N ตัวแปล** (หนึ่งตัวต่อรูปแบบ) แทนที่จะเป็น **N²** (ทุกคู่) +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. โครงสร้างโครงการ +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. การแยกย่อยแบบโมดูลต่อโมดูล +## 4. Module-by-Module Breakdown -### 4.1 การกำหนดค่า (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**แหล่งความจริงแหล่งเดียว** สำหรับการกำหนดค่าของผู้ให้บริการทั้งหมด +The **single source of truth** for all provider configuration. -| ไฟล์ | วัตถุประสงค์ | -| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` ออบเจ็กต์ที่มี URL พื้นฐาน ข้อมูลประจำตัว OAuth (ค่าเริ่มต้น) ส่วนหัว และระบบแจ้งเริ่มต้นสำหรับผู้ให้บริการทุกราย ยังกำหนด `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` และ `SKIP_PATTERNS` อีกด้วย | -| `credentialLoader.ts` | โหลดข้อมูลรับรองภายนอกจาก `data/provider-credentials.json` และรวมเข้ากับค่าเริ่มต้นที่ฮาร์ดโค้ดใน `PROVIDERS` เก็บความลับไว้นอกเหนือการควบคุมของแหล่งที่มาในขณะที่ยังคงความเข้ากันได้แบบย้อนหลัง | -| `providerModels.ts` | การลงทะเบียนโมเดลส่วนกลาง: นามแฝงของผู้ให้บริการแผนที่ → รหัสโมเดล ฟังก์ชันเช่น `getModels()`, `getProviderByAlias()` | -| `codexInstructions.ts` | คำแนะนำของระบบที่แทรกเข้าไปในคำขอ Codex (การแก้ไขข้อจำกัด กฎแซนด์บ็อกซ์ นโยบายการอนุมัติ) | -| `defaultThinkingSignature.ts` | ลายเซ็น "การคิด" เริ่มต้นสำหรับโมเดล Claude และ Gemini | -| `ollamaModels.ts` | คำจำกัดความของสคีมาสำหรับโมเดล Ollama ท้องถิ่น (ชื่อ ขนาด ตระกูล การหาปริมาณ) | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### ขั้นตอนการโหลดข้อมูลรับรอง +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 ผู้ดำเนินการ (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -ผู้ดำเนินการสรุป **ตรรกะเฉพาะของผู้ให้บริการ** โดยใช้ **รูปแบบกลยุทธ์** ตัวดำเนินการแต่ละตัวจะแทนที่วิธีพื้นฐานตามความจำเป็น +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| ผู้ดำเนินการ | ผู้ให้บริการ | ความเชี่ยวชาญพิเศษที่สำคัญ | -| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `base.ts` | — | ฐานบทคัดย่อ: การสร้าง URL, ส่วนหัว, ตรรกะการลองใหม่, การรีเฟรชข้อมูลรับรอง | -| `default.ts` | Claude, เมถุน, OpenAI, GLM, Kimi, MiniMax | การรีเฟรชโทเค็น OAuth ทั่วไปสำหรับผู้ให้บริการมาตรฐาน | -| `antigravity.ts` | รหัส Google Cloud | การสร้างรหัสโปรเจ็กต์/เซสชัน, ทางเลือกหลาย URL, ลองแยกวิเคราะห์ข้อความแสดงข้อผิดพลาดแบบกำหนดเองอีกครั้ง ("รีเซ็ตหลังจาก 2 ชม. 7 นาที 23 วินาที") | -| `cursor.ts` | เคอร์เซอร์ IDE | **ซับซ้อนที่สุด**: การตรวจสอบสิทธิ์การตรวจสอบ SHA-256, การเข้ารหัสคำขอ Protobuf, ไบนารี EventStream → การแยกวิเคราะห์การตอบสนอง SSE | -| `codex.ts` | OpenAI Codex | ใส่คำสั่งของระบบ จัดการระดับการคิด ลบพารามิเตอร์ที่ไม่รองรับ | -| `gemini-cli.ts` | Google ราศีเมถุน CLI | การสร้าง URL ที่กำหนดเอง (`streamGenerateContent`), การรีเฟรชโทเค็น Google OAuth | -| `github.ts` | นักบิน GitHub | ระบบโทเค็นคู่ (โทเค็น GitHub OAuth + โทเค็น Copilot) การเลียนแบบส่วนหัว VSCode | -| `kiro.ts` | AWS CodeWhisperer | การแยกวิเคราะห์ไบนารี AWS EventStream, เฟรมเหตุการณ์ AMZN, การประมาณโทเค็น | -| `index.ts` | — | โรงงาน: ชื่อผู้ให้บริการแผนที่ → คลาสผู้ดำเนินการ โดยมีค่าเริ่มต้นสำรอง | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 ตัวจัดการ (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**เลเยอร์การเรียบเรียง** — ประสานงานการแปล การดำเนินการ การสตรีม และการจัดการข้อผิดพลาด +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| ไฟล์ | วัตถุประสงค์ | -| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **ผู้เรียบเรียงกลาง** (~600 บรรทัด) จัดการวงจรคำขอที่สมบูรณ์: การตรวจจับรูปแบบ → การแปล → การส่งตัวดำเนินการ → การตอบสนองแบบสตรีมมิ่ง/ไม่สตรีมมิ่ง → การรีเฟรชโทเค็น → การจัดการข้อผิดพลาด → การบันทึกการใช้งาน | -| `responsesHandler.ts` | อะแดปเตอร์สำหรับ Responses API ของ OpenAI: แปลงรูปแบบการตอบกลับ → การแชทเสร็จสิ้น → ส่งไปที่ `chatCore` → แปลง SSE กลับเป็นรูปแบบการตอบกลับ | -| `embeddings.ts` | ตัวจัดการการสร้างการฝัง: แก้ไขโมเดลการฝัง → ผู้ให้บริการ, ส่งไปยัง API ของผู้ให้บริการ, ส่งคืนการตอบสนองการฝังที่เข้ากันได้กับ OpenAI รองรับผู้ให้บริการ 6+ ราย | -| `imageGeneration.ts` | ตัวจัดการการสร้างรูปภาพ: แก้ไขโมเดลรูปภาพ → ผู้ให้บริการ รองรับโหมดที่เข้ากันได้กับ OpenAI, Gemini-image (ต้านแรงโน้มถ่วง) และโหมดทางเลือก (Nebius) ส่งกลับภาพ base64 หรือ URL | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### ระยะเวลาคำขอ (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 บริการ (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -ตรรกะทางธุรกิจที่สนับสนุนตัวจัดการและผู้ดำเนินการ +Business logic that supports the handlers and executors. -| ไฟล์ | วัตถุประสงค์ | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **การตรวจจับรูปแบบ** (`detectFormat`): วิเคราะห์โครงสร้างคำขอเพื่อระบุรูปแบบ Claude/OpenAI/Gemini/Antigravity/Responses (รวมถึง `max_tokens` heuristic สำหรับ Claude) นอกจากนี้: การสร้าง URL, การสร้างส่วนหัว, การคิดการกำหนดค่าให้เป็นมาตรฐาน รองรับผู้ให้บริการแบบไดนามิก `openai-compatible-*` และ `anthropic-compatible-*` | -| `model.ts` | การแยกวิเคราะห์สตริงโมเดล (`claude/model-name` → `{provider: "claude", model: "model-name"}`), การแก้ไขนามแฝงด้วยการตรวจจับการชนกัน, การดูแลอินพุต (ปฏิเสธอักขระการแวะผ่านพาธ/อักขระควบคุม) และการแก้ไขข้อมูลโมเดลด้วยการสนับสนุน getter นามแฝง async | -| `accountFallback.ts` | การจัดการขีดจำกัดอัตรา: การถอยกลับแบบเอ็กซ์โปเนนเชียล (1 วินาที → 2 วินาที → 4 วินาที → สูงสุด 2 นาที), การจัดการคูลดาวน์บัญชี, การจัดหมวดหมู่ข้อผิดพลาด (ซึ่งข้อผิดพลาดทำให้เกิดทางเลือกเทียบกับไม่) | -| `tokenRefresh.ts` | การรีเฟรชโทเค็น OAuth สำหรับ **ผู้ให้บริการทุกราย**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth) รวมแคชการขจัดความซ้ำซ้อนตามสัญญาในเที่ยวบิน และลองอีกครั้งโดยใช้การแบ็คออฟแบบเอ็กซ์โปเนนเชียล | -| `combo.ts` | **โมเดลคอมโบ**: เชนของโมเดลสำรอง หากโมเดล A ล้มเหลวโดยมีข้อผิดพลาดที่มีสิทธิ์ใช้ทางเลือก ให้ลองใช้โมเดล B จากนั้นตามด้วย C ฯลฯ ส่งกลับรหัสสถานะอัปสตรีมจริง | -| `usage.ts` | ดึงข้อมูลโควต้า/การใช้งานจาก API ของผู้ให้บริการ (โควต้า GitHub Copilot, โควต้าโมเดล Antigravity, ขีดจำกัดอัตรา Codex, การแจกแจงการใช้งาน Kiro, การตั้งค่า Claude) | -| `accountSelector.ts` | การเลือกบัญชีอัจฉริยะพร้อมอัลกอริธึมการให้คะแนน: พิจารณาลำดับความสำคัญ สถานะสุขภาพ ตำแหน่งการวนซ้ำ และสถานะคูลดาวน์ เพื่อเลือกบัญชีที่เหมาะสมที่สุดสำหรับคำขอแต่ละรายการ | -| `contextManager.ts` | การจัดการวงจรชีวิตของคำขอ: สร้างและติดตามออบเจ็กต์บริบทต่อคำขอด้วยข้อมูลเมตา (ID คำขอ การประทับเวลา ข้อมูลผู้ให้บริการ) สำหรับการดีบักและการบันทึก | -| `ipFilter.ts` | การควบคุมการเข้าถึงตาม IP: รองรับโหมดรายการที่อนุญาตและรายการที่บล็อก ตรวจสอบ IP ไคลเอ็นต์กับกฎที่กำหนดค่าไว้ก่อนที่จะประมวลผลคำขอ API | -| `sessionManager.ts` | การติดตามเซสชันด้วยการพิมพ์ลายนิ้วมือไคลเอ็นต์: ติดตามเซสชันที่ใช้งานอยู่โดยใช้ตัวระบุไคลเอ็นต์แบบแฮช ตรวจสอบจำนวนคำขอ และจัดเตรียมตัววัดเซสชัน | -| `signatureCache.ts` | ขอแคชการขจัดข้อมูลซ้ำซ้อนตามลายเซ็น: ป้องกันคำขอที่ซ้ำกันโดยการแคชลายเซ็นคำขอล่าสุด และส่งคืนการตอบกลับที่แคชไว้สำหรับคำขอที่เหมือนกันภายในกรอบเวลา | -| `systemPrompt.ts` | การแทรกพร้อมท์ของระบบทั่วโลก: เพิ่มหรือต่อท้ายพรอมต์ระบบที่กำหนดค่าได้สำหรับคำขอทั้งหมด โดยมีการจัดการความเข้ากันได้ต่อผู้ให้บริการ | -| `thinkingBudget.ts` | การจัดการงบประมาณโทเค็นการใช้เหตุผล: รองรับโหมดส่งผ่าน, อัตโนมัติ (กำหนดค่าการคิดแบบสตริป), กำหนดเอง (งบประมาณคงที่) และโหมดการปรับตัว (ปรับขนาดความซับซ้อน) สำหรับการควบคุมโทเค็นการคิด/การใช้เหตุผล | -| `wildcardRouter.ts` | การกำหนดเส้นทางรูปแบบโมเดลไวด์การ์ด: แก้ไขรูปแบบไวด์การ์ด (เช่น `*/claude-*`) ให้เป็นคู่ผู้ให้บริการ/โมเดลที่เป็นรูปธรรมโดยขึ้นอยู่กับความพร้อมใช้งานและลำดับความสำคัญ | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### การรีเฟรชโทเค็นซ้ำซ้อน +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### เครื่องสถานะสำรองบัญชี +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### โซ่โมเดลคอมโบ +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 นักแปล (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**เครื่องมือแปลรูปแบบ** ใช้ระบบปลั๊กอินที่ลงทะเบียนด้วยตนเอง +The **format translation engine** using a self-registering plugin system. -#### สถาปัตยกรรม +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| ไดเรกทอรี | ไฟล์ | คำอธิบาย | -| ------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | นักแปล 8 คน | แปลงเนื้อหาคำขอระหว่างรูปแบบ แต่ละไฟล์ลงทะเบียนด้วยตนเองผ่าน `register(from, to, fn)` เมื่อนำเข้า | -| `response/` | นักแปล 7 คน | แปลงส่วนการตอบสนองการสตรีมระหว่างรูปแบบ จัดการประเภทเหตุการณ์ SSE, บล็อกการคิด, การเรียกใช้เครื่องมือ | -| `helpers/` | 6 ตัวช่วย | ยูทิลิตี้ที่ใช้ร่วมกัน: `claudeHelper` (การแยกพร้อมท์ของระบบ, การกำหนดค่าการคิด), `geminiHelper` (การแมปชิ้นส่วน/เนื้อหา), `openaiHelper` (การกรองรูปแบบ), `toolCallHelper` (การสร้าง ID, การแทรกการตอบสนองที่ขาดหายไป), `maxTokensHelper`, `responsesApiHelper` | -| `index.ts` | — | เครื่องมือการแปล: `translateRequest()`, `translateResponse()`, การจัดการสถานะ, การลงทะเบียน | -| `formats.ts` | — | รูปแบบค่าคงที่: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES` | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### การออกแบบหลัก: ปลั๊กอินที่ลงทะเบียนด้วยตนเอง +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 การใช้งาน (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| ไฟล์ | วัตถุประสงค์ | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | การสร้างการตอบสนองข้อผิดพลาด (รูปแบบที่เข้ากันได้กับ OpenAI), การแยกวิเคราะห์ข้อผิดพลาดอัปสตรีม, การแยกเวลาลองต้านแรงโน้มถ่วงอีกครั้งจากข้อความแสดงข้อผิดพลาด, การสตรีมข้อผิดพลาด SSE | -| `stream.ts` | **SSE Transform Stream** — ไปป์ไลน์การสตรีมหลัก สองโหมด: `TRANSLATE` (การแปลรูปแบบเต็ม) และ `PASSTHROUGH` (ทำให้เป็นมาตรฐาน + แยกการใช้งาน) จัดการการบัฟเฟอร์แบบก้อน การประมาณการใช้งาน การติดตามความยาวของเนื้อหา อินสแตนซ์ตัวเข้ารหัส/ตัวถอดรหัสต่อสตรีมหลีกเลี่ยงสถานะที่ใช้ร่วมกัน | -| `streamHelpers.ts` | ยูทิลิตี้ SSE ระดับต่ำ: `parseSSELine` (ทนต่อช่องว่าง), `hasValuableContent` (กรองส่วนว่างสำหรับ OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (การจัดลำดับ SSE ที่รับรู้รูปแบบด้วยการล้างข้อมูล `perf_metrics`) | -| `usageTracking.ts` | การแยกการใช้โทเค็นจากรูปแบบใดๆ (Claude/OpenAI/Gemini/Responses) การประมาณค่าด้วยอัตราส่วนเครื่องมือ/ข้อความที่แยกจากกันต่ออักขระ การเพิ่มบัฟเฟอร์ (อัตราความปลอดภัยของโทเค็น 2,000 โทเค็น) การกรองฟิลด์เฉพาะรูปแบบ การบันทึกคอนโซลด้วยสี ANSI | -| `requestLogger.ts` | การบันทึกคำขอตามไฟล์ (เลือกใช้ผ่าน `ENABLE_REQUEST_LOGS=true`) สร้างโฟลเดอร์เซสชันด้วยไฟล์ที่มีหมายเลขกำกับ: `1_req_client.json` → `7_res_client.txt` I/O ทั้งหมดเป็นแบบอะซิงโครนัส (fire-and-forget) มาสก์ส่วนหัวที่ละเอียดอ่อน | -| `bypassHandler.ts` | สกัดกั้นรูปแบบเฉพาะจาก Claude CLI (การแยกชื่อ การอุ่นเครื่อง การนับ) และส่งคืนการตอบกลับปลอมโดยไม่ต้องโทรหาผู้ให้บริการใดๆ รองรับทั้งสตรีมมิ่งและไม่สตรีมมิ่ง จำกัดโดยเจตนาไว้ที่ขอบเขตของ Claude CLI | -| `networkProxy.ts` | แก้ไข URL พร็อกซีขาออกสำหรับผู้ให้บริการที่กำหนดโดยมีความสำคัญ: การกำหนดค่าเฉพาะผู้ให้บริการ → การกำหนดค่าส่วนกลาง → ตัวแปรสภาพแวดล้อม (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`) รองรับการยกเว้น `NO_PROXY` กำหนดค่าแคชเป็นเวลา 30 วินาที | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### ไปป์ไลน์สตรีมมิ่ง SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### โครงสร้างเซสชันตัวบันทึกคำขอ +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 ชั้นแอปพลิเคชัน (`src/`) +### 4.7 Application Layer (`src/`) -| ไดเรกทอรี | วัตถุประสงค์ | -| ------------- | ------------------------------------------------------------------------------------- | -| `src/app/` | UI ของเว็บ, เส้นทาง API, มิดเดิลแวร์ด่วน, ตัวจัดการการเรียกกลับ OAuth | -| `src/lib/` | การเข้าถึงฐานข้อมูล (`localDb.ts`, `usageDb.ts`), การรับรองความถูกต้อง, ที่ใช้ร่วมกัน | -| `src/mitm/` | ยูทิลิตี้พร็อกซีแบบ Man-in-the-middle สำหรับการสกัดกั้นการรับส่งข้อมูลของผู้ให้บริการ | -| `src/models/` | คำจำกัดความของโมเดลฐานข้อมูล | -| `src/shared/` | Wrappers รอบฟังก์ชัน open-sse (ผู้ให้บริการ สตรีม ข้อผิดพลาด ฯลฯ) | -| `src/sse/` | ตัวจัดการตำแหน่งข้อมูล SSE ที่เชื่อมต่อไลบรารี open-sse ไปยังเส้นทางด่วน | -| `src/store/` | การจัดการสถานะแอปพลิเคชัน | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### เส้นทาง API ที่โดดเด่น +#### Notable API Routes -| เส้นทาง | วิธีการ | วัตถุประสงค์ | -| --------------------------------------------- | ------------ | ----------------------------------------------------------------------------- | ------- | -| `/api/provider-models` | รับ/โพสต์/ลบ | CRUD สำหรับโมเดลที่กำหนดเองต่อผู้ให้บริการ | -| `/api/models/catalog` | รับ | แค็ตตาล็อกรวมของทุกรุ่น (แชท การฝัง รูปภาพ กำหนดเอง) จัดกลุ่มตามผู้ให้บริการ | -| `/api/settings/proxy` | รับ/วาง/ลบ | การกำหนดค่าพร็อกซีขาออกแบบลำดับชั้น (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | โพสต์ | ตรวจสอบการเชื่อมต่อพร็อกซีและส่งคืน IP/เวลาแฝง | สาธารณะ | -| `/v1/providers/[provider]/chat/completions` | โพสต์ | การแชทต่อผู้ให้บริการโดยเฉพาะพร้อมการตรวจสอบความถูกต้องของโมเดล | -| `/v1/providers/[provider]/embeddings` | โพสต์ | การฝังต่อผู้ให้บริการโดยเฉพาะพร้อมการตรวจสอบความถูกต้องของโมเดล | -| `/v1/providers/[provider]/images/generations` | โพสต์ | การสร้างอิมเมจต่อผู้ให้บริการโดยเฉพาะพร้อมการตรวจสอบโมเดล | -| `/api/settings/ip-filter` | รับ/ใส่ | การจัดการรายการ IP ที่อนุญาต/รายการบล็อก | -| `/api/settings/thinking-budget` | รับ/ใส่ | การกำหนดค่างบประมาณโทเค็นการให้เหตุผล (ส่งผ่าน/อัตโนมัติ/กำหนดเอง/แบบปรับได้) | -| `/api/settings/system-prompt` | รับ/ใส่ | ระบบ Global พร้อมฉีดสำหรับทุกคำขอ | -| `/api/sessions` | รับ | การติดตามเซสชันและตัวชี้วัดที่ใช้งานอยู่ | -| `/api/rate-limits` | รับ | สถานะขีดจำกัดอัตราต่อบัญชี | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. รูปแบบการออกแบบที่สำคัญ +## 5. Key Design Patterns -### 5.1 การแปลแบบ Hub และ Spoke +### 5.1 Hub-and-Spoke Translation -ทุกรูปแบบแปลผ่าน **รูปแบบ OpenAI เป็นศูนย์กลาง** การเพิ่มผู้ให้บริการใหม่จำเป็นต้องมีการเขียนนักแปล **หนึ่งคู่** (ถึง/จาก OpenAI) ไม่ใช่ N คู่ +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 รูปแบบกลยุทธ์ผู้บริหาร +### 5.2 Executor Strategy Pattern -ผู้ให้บริการแต่ละรายมีคลาสตัวดำเนินการเฉพาะที่สืบทอดมาจาก `BaseExecutor` โรงงานใน `executors/index.ts` เลือกโรงงานที่เหมาะสมขณะรันไทม์ +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 ระบบปลั๊กอินลงทะเบียนด้วยตนเอง +### 5.3 Self-Registering Plugin System -โมดูลนักแปลลงทะเบียนตัวเองในการนำเข้าผ่าน `register()` การเพิ่มนักแปลใหม่เป็นเพียงการสร้างไฟล์และนำเข้าเท่านั้น +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 บัญชีสำรองพร้อม Exponential Backoff +### 5.4 Account Fallback with Exponential Backoff -เมื่อผู้ให้บริการส่งคืน 429/401/500 ระบบสามารถสลับไปยังบัญชีถัดไป โดยใช้คูลดาวน์แบบเอ็กซ์โพเนนเชียล (1 วินาที → 2 วินาที → 4 วินาที → สูงสุด 2 นาที) +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 โซ่รุ่นคอมโบ +### 5.5 Combo Model Chains -"คำสั่งผสม" จัดกลุ่มสตริง `provider/model` หลายรายการ หากรายการแรกล้มเหลว ให้ถอยกลับไปยังรายการถัดไปโดยอัตโนมัติ +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 การแปลสตรีมมิ่งแบบ stateful +### 5.6 Stateful Streaming Translation -การแปลการตอบสนองจะรักษาสถานะทั่วทั้งกลุ่ม SSE (การติดตามบล็อกความคิด การสะสมการเรียกเครื่องมือ การทำดัชนีบล็อกเนื้อหา) ผ่านกลไก `initState()` +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 บัฟเฟอร์ความปลอดภัยในการใช้งาน +### 5.7 Usage Safety Buffer -มีการเพิ่มบัฟเฟอร์ 2,000 โทเค็นในการใช้งานที่รายงาน เพื่อป้องกันไม่ให้ไคลเอ็นต์เข้าถึงขีดจำกัดหน้าต่างบริบท เนื่องจากโอเวอร์เฮดจากการแจ้งเตือนของระบบและการแปลรูปแบบ +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. รูปแบบที่รองรับ +## 6. Supported Formats -| รูปแบบ | ทิศทาง | ตัวระบุ | -| ------------------------ | --------------------- | ------------------ | -| การแชท OpenAI เสร็จสิ้น | แหล่งที่มา + เป้าหมาย | `openai` | -| API การตอบสนองของ OpenAI | แหล่งที่มา + เป้าหมาย | `openai-responses` | -| มานุษยวิทยาคลอด | แหล่งที่มา + เป้าหมาย | `claude` | -| Google ราศีเมถุน | แหล่งที่มา + เป้าหมาย | `gemini` | -| Google ราศีเมถุน CLI | กำหนดเป้าหมายเท่านั้น | `gemini-cli` | -| ต้านแรงโน้มถ่วง | แหล่งที่มา + เป้าหมาย | `antigravity` | -| AWS Kiro | กำหนดเป้าหมายเท่านั้น | `kiro` | -| เคอร์เซอร์ | กำหนดเป้าหมายเท่านั้น | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. ผู้ให้บริการที่รองรับ +## 7. Supported Providers -| ผู้ให้บริการ | วิธีการรับรองความถูกต้อง | ผู้ดำเนินการ | หมายเหตุสำคัญ | -| ------------------------ | ------------------------ | --------------- | ---------------------------------------------------- | -| มานุษยวิทยาคลอด | คีย์ API หรือ OAuth | ค่าเริ่มต้น | ใช้ `x-api-key` ส่วนหัว | -| Google ราศีเมถุน | คีย์ API หรือ OAuth | ค่าเริ่มต้น | ใช้ `x-goog-api-key` ส่วนหัว | -| Google ราศีเมถุน CLI | OAuth | GeminiCLI | ใช้ปลายทาง `streamGenerateContent` | -| ต้านแรงโน้มถ่วง | OAuth | ต้านแรงโน้มถ่วง | ทางเลือกหลาย URL, ลองแยกวิเคราะห์อีกครั้งแบบกำหนดเอง | -| OpenAI | คีย์ API | ค่าเริ่มต้น | ผู้ถือมาตรฐานรับรองความถูกต้อง | -| โคเด็กซ์ | OAuth | โคเด็กซ์ | อัดคำสั่งระบบ จัดการการคิด | -| นักบิน GitHub | OAuth + โทเค็น Copilot | Github | โทเค็นคู่, ส่วนหัว VSCode เลียนแบบ | -| คิโระ (AWS) | AWS SSO OIDC หรือโซเชียล | คิโระ | การแยกวิเคราะห์ EventStream ไบนารี | -| เคอร์เซอร์ IDE | การตรวจสอบความถูกต้อง | เคอร์เซอร์ | การเข้ารหัส Protobuf, เช็คซัม SHA-256 | -| ควีน | OAuth | ค่าเริ่มต้น | การรับรองมาตรฐาน | -| ไอโฟลว์ | OAuth (พื้นฐาน + ผู้ถือ) | ค่าเริ่มต้น | ส่วนหัวการรับรองความถูกต้องแบบคู่ | -| OpenRouter | คีย์ API | ค่าเริ่มต้น | ผู้ถือมาตรฐานรับรองความถูกต้อง | -| GLM, Kimi, MiniMax | คีย์ API | ค่าเริ่มต้น | เข้ากันได้กับ Claude ใช้ `x-api-key` | -| `openai-compatible-*` | คีย์ API | ค่าเริ่มต้น | ไดนามิก: จุดสิ้นสุดที่เข้ากันได้กับ OpenAI | -| `anthropic-compatible-*` | คีย์ API | ค่าเริ่มต้น | ไดนามิก: จุดสิ้นสุดที่เข้ากันได้กับ Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. สรุปการไหลของข้อมูล +## 8. Data Flow Summary -### คำขอสตรีมมิ่ง +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### คำขอที่ไม่ใช่สตรีมมิ่ง +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### บายพาสโฟลว์ (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/th/FEATURES.md b/docs/i18n/th/FEATURES.md index 93254c8bf8..82cc73b67b 100644 --- a/docs/i18n/th/FEATURES.md +++ b/docs/i18n/th/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute - แกลเลอรีคุณลักษณะแดชบอร์ด +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -ภาพแนะนำทุกส่วนของแดชบอร์ด OmniRoute +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 ผู้ให้บริการ +## 🔌 Providers -จัดการการเชื่อมต่อผู้ให้บริการ AI: ผู้ให้บริการ OAuth (Claude Code, Codex, Gemini CLI), ผู้ให้บริการคีย์ API (Groq, DeepSeek, OpenRouter) และผู้ให้บริการฟรี (iFlow, Qwen, Kiro) +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 คอมโบ +## 🎨 Combos -สร้างคอมโบการกำหนดเส้นทางแบบจำลองด้วย 6 กลยุทธ์: เติมก่อน ปัดเศษ ยกกำลังสองตัวเลือก สุ่ม ใช้น้อยที่สุด และปรับต้นทุนให้เหมาะสม แต่ละคอมโบเชื่อมโยงหลายรุ่นพร้อมทางเลือกอัตโนมัติ +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 การวิเคราะห์ +## 📊 Analytics -การวิเคราะห์การใช้งานที่ครอบคลุมด้วยการใช้โทเค็น การประมาณการต้นทุน แผนที่ความร้อนของกิจกรรม แผนภูมิการกระจายรายสัปดาห์ และรายละเอียดต่อผู้ให้บริการ +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 สุขภาพของระบบ +## 🏥 System Health -การตรวจสอบแบบเรียลไทม์: เวลาทำงาน หน่วยความจำ เวอร์ชัน เปอร์เซ็นต์ไทล์แฝง (p50/p95/p99) สถิติแคช และสถานะเซอร์กิตเบรกเกอร์ของผู้ให้บริการ +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## ???? สนามเด็กเล่นนักแปล +## 🔧 Translator Playground -สี่โหมดสำหรับการดีบักการแปล API: **Playground** (ตัวแปลงรูปแบบ), **Chat Tester** (คำขอสด), **Test Bench** (การทดสอบเป็นกลุ่ม) และ **Live Monitor** (สตรีมแบบเรียลไทม์) +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ การตั้งค่า +## 🎮 Model Playground _(v2.0.9+)_ -การตั้งค่าทั่วไป ที่เก็บข้อมูลระบบ การจัดการการสำรองข้อมูล (ฐานข้อมูลส่งออก/นำเข้า) ลักษณะที่ปรากฏ (โหมดมืด/สว่าง) ความปลอดภัย (รวมถึงการป้องกันจุดสิ้นสุด API และการบล็อกผู้ให้บริการแบบกำหนดเอง) การกำหนดเส้นทาง ความยืดหยุ่น และการกำหนดค่าขั้นสูง +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🛠 เครื่องมือ CLI +## 🔧 CLI Tools -การกำหนดค่าเพียงคลิกเดียวสำหรับเครื่องมือเข้ารหัส AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code และ Antigravity +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## ⏩ ขอบันทึก +## 🤖 CLI Agents _(v2.0.11+)_ -การบันทึกคำขอแบบเรียลไทม์พร้อมการกรองตามผู้ให้บริการ โมเดล บัญชี และคีย์ API แสดงรหัสสถานะ การใช้โทเค็น เวลาแฝง และรายละเอียดการตอบกลับ +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 จุดสิ้นสุด API +## 🌐 API Endpoint -ตำแหน่งข้อมูล API แบบรวมของคุณพร้อมรายละเอียดความสามารถ: การแชทให้เสร็จสิ้น การฝัง การสร้างรูปภาพ การจัดอันดับใหม่ การถอดเสียง และคีย์ API ที่ลงทะเบียน +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/th/TROUBLESHOOTING.md b/docs/i18n/th/TROUBLESHOOTING.md index c68d793a6b..120092d63c 100644 --- a/docs/i18n/th/TROUBLESHOOTING.md +++ b/docs/i18n/th/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# การแก้ไขปัญหา +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -ปัญหาและวิธีแก้ปัญหาทั่วไปสำหรับ OmniRoute +Common problems and solutions for OmniRoute. --- -## แก้ไขด่วน +## Quick Fixes -| ปัญหา | โซลูชั่น | -| ------------------------------- | ---------------------------------------------------------------------- | -| การเข้าสู่ระบบครั้งแรกไม่ทำงาน | ทำเครื่องหมาย `INITIAL_PASSWORD` ใน `.env` (ค่าเริ่มต้น: `123456`) | -| แดชบอร์ดเปิดบนพอร์ตผิด | ตั้งค่า `PORT=20128` และ `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| ไม่มีบันทึกคำขอภายใต้ `logs/` | ตั้งค่า `ENABLE_REQUEST_LOGS=true` | -| EACCES: การอนุญาตถูกปฏิเสธ | ตั้งค่า `DATA_DIR=/path/to/writable/dir` เพื่อแทนที่ `~/.omniroute` | -| กลยุทธ์การกำหนดเส้นทางไม่บันทึก | อัปเดตเป็น v1.4.11+ (แก้ไข Zod schema สำหรับการคงอยู่ของการตั้งค่า) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## ปัญหาของผู้ให้บริการ +## Provider Issues -### "โมเดลภาษาไม่ได้ให้ข้อความ" +### "Language model did not provide messages" -**สาเหตุ:** โควต้าของผู้ให้บริการหมดลง +**Cause:** Provider quota exhausted. -**แก้ไข:** +**Fix:** -1. ตรวจสอบตัวติดตามโควต้าแดชบอร์ด -2. ใช้คอมโบที่มีระดับทางเลือก -3. เปลี่ยนไปใช้ระดับที่ถูกกว่า/ฟรี +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### การจำกัดอัตรา +### Rate Limiting -**สาเหตุ:** โควต้าการสมัครใช้งานหมดลง +**Cause:** Subscription quota exhausted. -**แก้ไข:** +**Fix:** -- เพิ่มทางเลือก: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- ใช้ GLM/MiniMax เป็นข้อมูลสำรองราคาถูก +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### โทเค็น OAuth หมดอายุแล้ว +### OAuth Token Expired -OmniRoute รีเฟรชโทเค็นอัตโนมัติ หากปัญหายังคงอยู่: +OmniRoute auto-refreshes tokens. If issues persist: -1. แดชบอร์ด → ผู้ให้บริการ → เชื่อมต่อใหม่ -2. ลบและเพิ่มการเชื่อมต่อผู้ให้บริการอีกครั้ง +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## ปัญหาคลาวด์ +## Cloud Issues -### ข้อผิดพลาดการซิงค์คลาวด์ +### Cloud Sync Errors -1. ตรวจสอบ `BASE_URL` ชี้ไปยังอินสแตนซ์ที่ทำงานอยู่ของคุณ (เช่น `http://localhost:20128`) -2. ตรวจสอบ `CLOUD_URL` ชี้ไปยังจุดสิ้นสุดระบบคลาวด์ของคุณ (เช่น `https://omniroute.dev`) -3. เก็บค่า `NEXT_PUBLIC_*` ให้สอดคล้องกับค่าฝั่งเซิร์ฟเวอร์ +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### คลาวด์ `stream=false` ส่งคืน 500 +### Cloud `stream=false` Returns 500 -**อาการ:** `Unexpected token 'd'...` บนจุดปลายทางคลาวด์สำหรับการโทรที่ไม่ใช่การสตรีม +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**สาเหตุ:** อัปสตรีมส่งคืนเพย์โหลด SSE ในขณะที่ไคลเอ็นต์คาดหวัง JSON +**Cause:** Upstream returns SSE payload while client expects JSON. -**วิธีแก้ปัญหา:** ใช้ `stream=true` สำหรับการโทรโดยตรงบนคลาวด์ รันไทม์ในเครื่องรวมถึงทางเลือก SSE → JSON +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud บอกว่าเชื่อมต่อแล้ว แต่ "คีย์ API ไม่ถูกต้อง" +### Cloud Says Connected but "Invalid API key" -1. สร้างคีย์ใหม่จากแดชบอร์ดในเครื่อง (`/api/keys`) -2. เรียกใช้คลาวด์ซิงค์: เปิดใช้งานคลาวด์ → ซิงค์ทันที -3. คีย์เก่า/ที่ไม่ได้ซิงค์ยังสามารถส่งคืน `401` บนคลาวด์ได้ +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## ปัญหานักเทียบท่า +## Docker Issues -### เครื่องมือ CLI แสดงว่าไม่ได้ติดตั้ง +### CLI Tool Shows Not Installed -1. ตรวจสอบฟิลด์รันไทม์: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. สำหรับโหมดพกพา: ใช้เป้าหมายรูปภาพ `runner-cli` (CLI ที่รวมกลุ่ม) -3. สำหรับโหมดเมาต์โฮสต์: ตั้งค่า `CLI_EXTRA_PATHS` และเมาต์ไดเร็กทอรี bin โฮสต์เป็นแบบอ่านอย่างเดียว -4. หาก `installed=true` และ `runnable=false`: พบไบนารีแต่ตรวจสุขภาพไม่สำเร็จ +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### การตรวจสอบรันไทม์ด่วน +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## ปัญหาต้นทุน +## Cost Issues -### ต้นทุนสูง +### High Costs -1. ตรวจสอบสถิติการใช้งานในแดชบอร์ด → การใช้งาน -2. สลับโมเดลหลักเป็น GLM/MiniMax -3. ใช้ Free Tier (Gemini CLI, iFlow) สำหรับงานที่ไม่สำคัญ -4. กำหนดงบประมาณต้นทุนต่อคีย์ API: แดชบอร์ด → คีย์ API → งบประมาณ +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## การดีบัก +## Debugging -### เปิดใช้งานบันทึกคำขอ +### Enable Request Logs -ตั้งค่า `ENABLE_REQUEST_LOGS=true` ในไฟล์ `.env` ของคุณ บันทึกจะปรากฏภายใต้ไดเรกทอรี `logs/` +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### ตรวจสอบสุขภาพของผู้ให้บริการ +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### พื้นที่เก็บข้อมูลรันไทม์ +### Runtime Storage -- สถานะหลัก: `${DATA_DIR}/db.json` (ผู้ให้บริการ คอมโบ นามแฝง คีย์ การตั้งค่า) -- การใช้งาน: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- บันทึกคำขอ: `/logs/...` (เมื่อ `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## ปัญหาเซอร์กิตเบรกเกอร์ +## Circuit Breaker Issues -### ผู้ให้บริการติดอยู่ในสถานะเปิด +### Provider stuck in OPEN state -เมื่อเซอร์กิตเบรกเกอร์ของผู้ให้บริการเปิดอยู่ คำขอจะถูกบล็อกจนกว่าคูลดาวน์จะหมดลง +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**แก้ไข:** +**Fix:** -1. ไปที่ **แดชบอร์ด → การตั้งค่า → ความยืดหยุ่น** -2. ตรวจสอบการ์ดเซอร์กิตเบรกเกอร์สำหรับผู้ให้บริการที่ได้รับผลกระทบ -3. คลิก **รีเซ็ตทั้งหมด** เพื่อล้างเบรกเกอร์ทั้งหมด หรือรอให้คูลดาวน์หมดลง -4. ตรวจสอบว่าผู้ให้บริการพร้อมใช้งานจริงก่อนที่จะรีเซ็ต +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### ผู้ให้บริการสะดุดเบรกเกอร์อย่างต่อเนื่อง +### Provider keeps tripping the circuit breaker -หากผู้ให้บริการเข้าสู่สถานะเปิดซ้ำๆ: +If a provider repeatedly enters OPEN state: -1. ตรวจสอบ **แดชบอร์ด → สุขภาพ → สุขภาพของผู้ให้บริการ** เพื่อดูรูปแบบความล้มเหลว -2. ไปที่ **การตั้งค่า → ความยืดหยุ่น → โปรไฟล์ผู้ให้บริการ** และเพิ่มเกณฑ์ความล้มเหลว -3. ตรวจสอบว่าผู้ให้บริการได้เปลี่ยนแปลงขีดจำกัด API หรือต้องมีการตรวจสอบสิทธิ์อีกครั้งหรือไม่ -4. ตรวจสอบการวัดและส่งข้อมูลทางไกลเวลาแฝง — เวลาแฝงสูงอาจทำให้เกิดความล้มเหลวตามการหมดเวลา +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## ปัญหาการถอดเสียง +## Audio Transcription Issues -### ข้อผิดพลาด "รุ่นที่ไม่รองรับ" +### "Unsupported model" error -- ตรวจสอบให้แน่ใจว่าคุณใช้คำนำหน้าที่ถูกต้อง: `deepgram/nova-3` หรือ `assemblyai/best` -- ตรวจสอบว่าผู้ให้บริการเชื่อมต่ออยู่ใน **Dashboard → Providers** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### การถอดเสียงกลับว่างเปล่าหรือล้มเหลว +### Transcription returns empty or fails -- ตรวจสอบรูปแบบเสียงที่รองรับ: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- ตรวจสอบขนาดไฟล์อยู่ภายในขีดจำกัดของผู้ให้บริการ (โดยทั่วไปคือ <25MB) -- ตรวจสอบความถูกต้องของคีย์ API ของผู้ให้บริการในการ์ดผู้ให้บริการ +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## การแก้ไขจุดบกพร่องของนักแปล +## Translator Debugging -ใช้ **แดชบอร์ด → ตัวแปล** เพื่อแก้ไขปัญหาการแปลรูปแบบ: +Use **Dashboard → Translator** to debug format translation issues: -| โหมด | เมื่อใดควรใช้ | -| ---------------------- | ------------------------------------------------------------------------------------ | ------- | -| **สนามเด็กเล่น** | เปรียบเทียบรูปแบบอินพุต/เอาต์พุตแบบเคียงข้างกัน — วางคำขอที่ล้มเหลวเพื่อดูว่าคำขอแปล | อย่างไร | -| **เครื่องมือทดสอบแชท** | ส่งข้อความสดและตรวจสอบเพย์โหลดคำขอ/การตอบกลับทั้งหมด รวมถึงส่วนหัว | -| **ม้านั่งทดสอบ** | เรียกใช้การทดสอบเป็นชุดระหว่างรูปแบบต่างๆ เพื่อดูว่าคำแปลใดเสียหาย | -| **ถ่ายทอดสด** | ดูขั้นตอนคำขอแบบเรียลไทม์เพื่อตรวจจับปัญหาการแปลเป็นระยะๆ | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### ปัญหารูปแบบทั่วไป +### Common format issues -- **แท็กการคิดไม่ปรากฏ** — ตรวจสอบว่าผู้ให้บริการเป้าหมายสนับสนุนการคิดและการตั้งค่างบประมาณการคิดหรือไม่ -- **การเรียกเครื่องมือลดลง** — การแปลรูปแบบบางรูปแบบอาจตัดช่องที่ไม่รองรับออก ตรวจสอบในโหมดสนามเด็กเล่น -- **การแจ้งเตือนของระบบหายไป** — ระบบแจ้งของ Claude และ Gemini แตกต่างกัน ตรวจสอบผลลัพธ์การแปล -- **SDK ส่งคืนสตริงดิบแทนที่จะเป็นวัตถุ** — แก้ไขในเวอร์ชัน 1.1.0: ตอนนี้ตัวล้างการตอบสนองจะตัดฟิลด์ที่ไม่ได้มาตรฐาน (`x_groq`, `usage_breakdown` ฯลฯ) ที่ทำให้การตรวจสอบ OpenAI SDK Pydantic ล้มเหลว -- **GLM/ERNIE ปฏิเสธบทบาท `system`** — แก้ไขในเวอร์ชัน 1.1.0: บทบาท Normalizer จะรวมข้อความระบบเข้ากับข้อความผู้ใช้โดยอัตโนมัติสำหรับรุ่นที่เข้ากันไม่ได้ -- **`developer` ไม่รู้จักบทบาท** — แก้ไขใน v1.1.0: แปลงเป็น `system` โดยอัตโนมัติสำหรับผู้ให้บริการที่ไม่ใช่ OpenAI -- **`json_schema` ไม่ทำงานกับ Gemini** — แก้ไขใน v1.1.0: `response_format` ตอนนี้ถูกแปลงเป็น `responseMimeType` + `responseSchema` ของ Gemini แล้ว +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## การตั้งค่าความยืดหยุ่น +## Resilience Settings -### ขีดจำกัดอัตราอัตโนมัติไม่ทริกเกอร์ +### Auto rate-limit not triggering -- การจำกัดอัตราอัตโนมัติใช้กับผู้ให้บริการคีย์ API เท่านั้น (ไม่ใช่ OAuth/การสมัครสมาชิก) -- ตรวจสอบ **การตั้งค่า → ความยืดหยุ่น → โปรไฟล์ผู้ให้บริการ** ได้เปิดใช้งานการจำกัดอัตราอัตโนมัติแล้ว -- ตรวจสอบว่าผู้ให้บริการส่งคืนรหัสสถานะ `429` หรือส่วนหัว `Retry-After` หรือไม่ +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### การปรับแต่งการถอยกลับแบบเอ็กซ์โปเนนเชียล +### Tuning exponential backoff -โปรไฟล์ผู้ให้บริการรองรับการตั้งค่าเหล่านี้: +Provider profiles support these settings: -- **ความล่าช้าพื้นฐาน** — เวลารอเริ่มต้นหลังจากความล้มเหลวครั้งแรก (ค่าเริ่มต้น: 1 วินาที) -- **ความล่าช้าสูงสุด** — ขีดจำกัดเวลารอสูงสุด (ค่าเริ่มต้น: 30 วินาที) -- **ตัวคูณ** — จะต้องเพิ่มความล่าช้าเท่าใดต่อความล้มเหลวติดต่อกัน (ค่าเริ่มต้น: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### ฝูงต่อต้านฟ้าร้อง +### Anti-thundering herd -เมื่อคำขอหลายรายการส่งถึงผู้ให้บริการที่จำกัดอัตรา OmniRoute จะใช้ mutex + การจำกัดอัตราอัตโนมัติเพื่อซีเรียลไลซ์คำขอและป้องกันความล้มเหลวแบบเรียงซ้อน นี่เป็นแบบอัตโนมัติสำหรับผู้ให้บริการคีย์ API +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## ยังติดอยู่เหรอ? +## Optional RAG / LLM failure taxonomy (16 problems) -- **ปัญหา GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **สถาปัตยกรรม**: ดู [link](ARCHITECTURE.md) สำหรับรายละเอียดภายใน -- **การอ้างอิง API**: ดู [link](API_REFERENCE.md) สำหรับจุดสิ้นสุดทั้งหมด -- **แดชบอร์ดสุขภาพ**: ตรวจสอบ **แดชบอร์ด → สุขภาพ** เพื่อดูสถานะของระบบแบบเรียลไทม์ -- **นักแปล**: ใช้ **แดชบอร์ด → นักแปล** เพื่อแก้ไขปัญหาเกี่ยวกับรูปแบบ +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/th/USER_GUIDE.md b/docs/i18n/th/USER_GUIDE.md index c77a4d7d3b..5a043224df 100644 --- a/docs/i18n/th/USER_GUIDE.md +++ b/docs/i18n/th/USER_GUIDE.md @@ -1,12 +1,12 @@ -# คู่มือการใช้งาน +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -คู่มือฉบับสมบูรณ์สำหรับการกำหนดค่าผู้ให้บริการ การสร้างคอมโบ การผสานรวมเครื่องมือ CLI และการปรับใช้ OmniRoute +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## สารบัญ +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 ราคาโดยสรุป +## 💰 Pricing at a Glance -| ชั้น | ผู้ให้บริการ | ราคา | รีเซ็ตโควต้า | ดีที่สุดสำหรับ | -| ------------------ | ---------------- | ---------------- | ------------------- | ---------------------------- | -| **💳 สมัครสมาชิก** | รหัสคลอดด์ (Pro) | $20/เดือน | 5 ชม. + รายสัปดาห์ | สมัครสมาชิกแล้ว | -| | Codex (พลัส/โปร) | $20-200/เดือน | 5 ชม. + รายสัปดาห์ | ผู้ใช้ OpenAI | -| | ราศีเมถุน CLI | **ฟรี** | 180K/เดือน + 1K/วัน | ทุกคน! | -| | นักบิน GitHub | $10-19/เดือน | รายเดือน | ผู้ใช้ GitHub | -| **🔑 คีย์ API** | DeepSeek | จ่ายตามการใช้งาน | ไม่มี | การใช้เหตุผลราคาถูก | -| | กรอค | จ่ายตามการใช้งาน | ไม่มี | การอนุมานที่รวดเร็วเป็นพิเศษ | -| | xAI (โกรก) | จ่ายตามการใช้งาน | ไม่มี | Grok 4 การใช้เหตุผล | -| | มิสทรัล | จ่ายตามการใช้งาน | ไม่มี | โมเดลที่โฮสต์โดยสหภาพยุโรป | -| | ความฉงนสนเท่ห์ | จ่ายตามการใช้งาน | ไม่มี | การค้นหาเสริม | -| | ร่วมกัน AI | จ่ายตามการใช้งาน | ไม่มี | โมเดลโอเพ่นซอร์ส | -| | ดอกไม้ไฟ AI | จ่ายตามการใช้งาน | ไม่มี | ภาพ FLUX ที่รวดเร็ว | -| | สมอง | จ่ายตามการใช้งาน | ไม่มี | ความเร็วระดับเวเฟอร์ | -| | เชื่อมโยง | จ่ายตามการใช้งาน | ไม่มี | คำสั่ง R+ RAG | -| | NVIDIA NIM | จ่ายตามการใช้งาน | ไม่มี | โมเดลองค์กร | -| **💰 ราคาถูก** | GLM-4.7 | $0.6/1M | ทุกวัน 10.00 น. | สำรองงบประมาณ | -| | MiniMax M2.1 | $0.2/1M | กลิ้ง 5 ชั่วโมง | ตัวเลือกที่ถูกที่สุด | -| | คิมิ K2 | $9/เดือน คงที่ | 10M โทเค็น/เดือน | ต้นทุนที่คาดการณ์ได้ | -| **🆓 ฟรี** | ไอโฟลว์ | $0 | ไม่จำกัด | ฟรี 8 รุ่น | -| | ควีน | $0 | ไม่จำกัด | ฟรี 3 รุ่น | -| | คิโระ | $0 | ไม่จำกัด | คลอดด์ฟรี | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 เคล็ดลับสำหรับมืออาชีพ:** เริ่มต้นด้วย Gemini CLI (ฟรี 180,000 ต่อเดือน) + iFlow (ฟรีไม่จำกัด) คอมโบ = ค่าใช้จ่าย $0! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 กรณีการใช้งาน +## 🎯 Use Cases -### กรณีที่ 1: "ฉันสมัครสมาชิก Claude Pro" +### Case 1: "I have Claude Pro subscription" -**ปัญหา:** โควต้าหมดอายุโดยไม่ได้ใช้ อัตราจำกัดระหว่างการเขียนโค้ดจำนวนมาก +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### กรณีที่ 2: "ฉันต้องการต้นทุนเป็นศูนย์" +### Case 2: "I want zero cost" -**ปัญหา:** ไม่สามารถสมัครสมาชิกได้ ต้องการการเข้ารหัส AI ที่เชื่อถือได้ +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### กรณีที่ 3: "ฉันต้องการการเข้ารหัสตลอด 24 ชั่วโมงทุกวัน ไม่มีการหยุดชะงัก" +### Case 3: "I need 24/7 coding, no interruptions" -**ปัญหา:** กำหนดเวลา ไม่สามารถหยุดการทำงานได้ +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### กรณีที่ 4: "ฉันต้องการ AI ฟรีใน OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**ปัญหา:** ต้องการผู้ช่วย AI ในแอปส่งข้อความ ไม่มีค่าใช้จ่ายใดๆ ทั้งสิ้น +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 การตั้งค่าผู้ให้บริการ +## 📖 Provider Setup -### 🔐 ผู้ให้บริการสมัครสมาชิก +### 🔐 Subscription Providers -#### รหัสคลอด (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**เคล็ดลับสำหรับมือโปร:** ใช้ Opus สำหรับงานที่ซับซ้อน และใช้ Sonnet เพื่อความรวดเร็ว โควต้าการติดตาม OmniRoute ต่อรุ่น! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### OpenAI Codex (พลัส/โปร) +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (ฟรี 180K/เดือน!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**คุ้มค่าที่สุด:** ระดับฟรีมหาศาล! ใช้สิ่งนี้ก่อนระดับที่ชำระเงิน +**Best Value:** Huge free tier! Use this before paid tiers. -#### นักบิน GitHub +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 ผู้ให้บริการราคาถูก +### 💰 Cheap Providers -#### GLM-4.7 (รีเซ็ตรายวัน, $0.6/1M) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. ลงทะเบียน: [Zhipu AI](https://open.bigmodel.cn/) -2. รับคีย์ API จาก Coding Plan -3. แดชบอร์ด → เพิ่มคีย์ API: ผู้ให้บริการ: `glm`, คีย์ API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**ใช้:** `glm/glm-4.7` — **เคล็ดลับสำหรับมืออาชีพ:** แผนการเขียนโค้ดเสนอโควต้า 3× ในราคา 1/7! รีเซ็ตทุกวัน 10.00 น. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (รีเซ็ต 5 ชม., $0.20/1M) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. ลงทะเบียน: [MiniMax](https://www.minimax.io/) -2. รับคีย์ API → แดชบอร์ด → เพิ่มคีย์ API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**ใช้:** `minimax/MiniMax-M2.1` — **เคล็ดลับสำหรับมือโปร:** ตัวเลือกที่ถูกที่สุดสำหรับบริบทแบบยาว (โทเค็น 1M)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/เดือน) +#### Kimi K2 ($9/month flat) -1. สมัครสมาชิก: [Moonshot AI](https://platform.moonshot.ai/) -2. รับคีย์ API → แดชบอร์ด → เพิ่มคีย์ API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**ใช้:** `kimi/kimi-latest` — **เคล็ดลับสำหรับมืออาชีพ:** แก้ไข $9/เดือนสำหรับโทเค็น 10M = $0.90/ต้นทุนจริง 1M! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 ผู้ให้บริการฟรี +### 🆓 FREE Providers -#### iFlow (ฟรี 8 รุ่น) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (ฟรี 3 รุ่น) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### คิโระ (โคลด ฟรี) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 คอมโบ +## 🎨 Combos -### ตัวอย่างที่ 1: เพิ่มการสมัครสมาชิกให้สูงสุด → การสำรองข้อมูลราคาถูก +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### ตัวอย่างที่ 2: ฟรีเท่านั้น (ไม่มีค่าใช้จ่าย) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## สมบูรณ์ บูรณาการ CLI +## 🔧 CLI Integration -### เคอร์เซอร์ IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### รหัสคลอด +### Claude Code -แก้ไข `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -279,9 +279,9 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### โอเพ่นคลอว์ +### OpenClaw -แก้ไข `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ codex "your prompt" } ``` -**หรือใช้แดชบอร์ด:** เครื่องมือ CLI → OpenClaw → กำหนดค่าอัตโนมัติ +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### ไคลน์ / ดำเนินการต่อ / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 การปรับใช้ +## 🚀 Deployment -### การปรับใช้ VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### นักเทียบท่า +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,68 +403,72 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -สำหรับโหมดรวมโฮสต์ที่มีไบนารี CLI โปรดดูส่วนนักเทียบท่าในเอกสารหลัก +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### ตัวแปรสภาพแวดล้อม +### Environment Variables -| ตัวแปร | ค่าเริ่มต้น | คำอธิบาย | -| --------------------- | ------------------------------------ | ------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | เคล็ดลับการลงนาม JWT (**การเปลี่ยนแปลงในการผลิต**) | -| `INITIAL_PASSWORD` | `123456` | รหัสผ่านเข้าสู่ระบบครั้งแรก | -| `DATA_DIR` | `~/.omniroute` | ไดเร็กทอรีข้อมูล (db, การใช้งาน, บันทึก) | -| `PORT` | ค่าเริ่มต้นของเฟรมเวิร์ก | พอร์ตบริการ (`20128` ในตัวอย่าง) | -| `HOSTNAME` | ค่าเริ่มต้นของเฟรมเวิร์ก | ผูกโฮสต์ (ค่าเริ่มต้นของ Docker คือ `0.0.0.0`) | -| `NODE_ENV` | รันไทม์เริ่มต้น | ตั้งค่า `production` สำหรับการปรับใช้ | -| `BASE_URL` | `http://localhost:20128` | URL ฐานภายในฝั่งเซิร์ฟเวอร์ | -| `CLOUD_URL` | `https://omniroute.dev` | URL ฐานปลายทางการซิงค์บนคลาวด์ | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | ข้อมูลลับ HMAC สำหรับคีย์ API ที่สร้างขึ้น | -| `REQUIRE_API_KEY` | `false` | บังคับใช้คีย์ Bearer API บน `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | เปิดใช้งานบันทึกคำขอ/การตอบกลับ | -| `AUTH_COOKIE_SECURE` | `false` | บังคับ `Secure` คุกกี้รับรองความถูกต้อง (หลังพร็อกซีย้อนกลับ HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -สำหรับการอ้างอิงตัวแปรสภาพแวดล้อมแบบเต็ม โปรดดูที่ [README](../README.md) +For the full environment variable reference, see the [README](../README.md). --- -## 📊 รุ่นที่มีจำหน่าย +## 📊 Available Models
-ดูรุ่นที่มีทั้งหมด -**รหัสโคลด (`cc/`)** — โปร/สูงสุด: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +View all available models -**โคเด็กซ์ (`cx/`)** — บวก/โปร: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**ราศีเมถุน CLI (`gc/`)** — ฟรี: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**โปรแกรมควบคุม GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` + +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` **GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` **MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — ฟรี: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**คิวเวน (`qw/`)** — ฟรี: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**คิโระ (`kr/`)** — ฟรี: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` -**ดีพซีค (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` -**โกรก (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` **xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**มิสทรัล (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**ความสับสน (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -** AI ร่วมกัน (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**ดอกไม้ไฟ AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**เซรีบร้า (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**เชื่อมโยงกัน (`cohere/`)**: `cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` **NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` @@ -416,11 +476,11 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat --- -## 🧩 คุณสมบัติขั้นสูง +## 🧩 Advanced Features -### โมเดลที่กำหนดเอง +### Custom Models -เพิ่ม ID รุ่นใดๆ ให้กับผู้ให้บริการโดยไม่ต้องรอการอัปเดตแอป: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -432,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -หรือใช้แดชบอร์ด: **ผู้ให้บริการ → [ผู้ให้บริการ] → โมเดลที่กำหนดเอง** +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### เส้นทางของผู้ให้บริการเฉพาะ +### Dedicated Provider Routes -กำหนดเส้นทางคำขอโดยตรงไปยังผู้ให้บริการเฉพาะด้วยการตรวจสอบโมเดล: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -444,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -คำนำหน้าผู้ให้บริการจะถูกเพิ่มอัตโนมัติหากไม่มี โมเดลที่ไม่ตรงกันส่งคืน `400` +The provider prefix is auto-added if missing. Mismatched models return `400`. -### การกำหนดค่าพร็อกซีเครือข่าย +### Network Proxy Configuration ```bash # Set global proxy @@ -462,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**ลำดับความสำคัญ:** เฉพาะคีย์ → เฉพาะคอมโบ → เฉพาะผู้ให้บริการ → ทั่วโลก → สภาพแวดล้อม +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### โมเดลแคตตาล็อก API +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -ส่งคืนโมเดลที่จัดกลุ่มตามผู้ให้บริการที่มีประเภท (`chat`, `embedding`, `image`) +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### คลาวด์ซิงค์ +### Cloud Sync -- ซิงค์ผู้ให้บริการ คอมโบ และการตั้งค่าระหว่างอุปกรณ์ต่างๆ -- การซิงค์พื้นหลังอัตโนมัติพร้อมการหมดเวลา + ล้มเหลวอย่างรวดเร็ว -- ต้องการ `BASE_URL`/`CLOUD_URL` ฝั่งเซิร์ฟเวอร์ในการใช้งานจริง +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (ระยะที่ 9) +### LLM Gateway Intelligence (Phase 9) -- **Semantic Cache** — แคชอัตโนมัติไม่สตรีม อุณหภูมิ=0 การตอบสนอง (บายพาสด้วย `X-OmniRoute-No-Cache: true`) -- **คำขอ Idempotency** — กรองคำขอที่ซ้ำกันภายใน 5 วินาทีผ่านส่วนหัว `Idempotency-Key` หรือ `X-Request-Id` -- **การติดตามความคืบหน้า** — เลือกใช้กิจกรรม SSE `event: progress` ผ่านส่วนหัว `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### สนามเด็กเล่นนักแปล +### Translator Playground -เข้าถึงได้ผ่าน **Dashboard → Translator** แก้ไขข้อบกพร่องและเห็นภาพว่า OmniRoute แปลคำขอ API ระหว่างผู้ให้บริการอย่างไร +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| โหมด | วัตถุประสงค์ | -| ---------------------- | ---------------------------------------------------------------------------------- | -| **สนามเด็กเล่น** | เลือกรูปแบบต้นทาง/เป้าหมาย วางคำขอ และดูผลลัพธ์ที่แปลได้ทันที | -| **เครื่องมือทดสอบแชท** | ส่งข้อความแชทสดผ่านพร็อกซีและตรวจสอบรอบคำขอ/การตอบกลับทั้งหมด | -| **ม้านั่งทดสอบ** | เรียกใช้การทดสอบเป็นกลุ่มโดยใช้รูปแบบต่างๆ ร่วมกันเพื่อตรวจสอบความถูกต้องของการแปล | -| **ถ่ายทอดสด** | ดูการแปลแบบเรียลไทม์ตามคำขอที่ไหลผ่านพร็อกซี | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**กรณีการใช้งาน:** +**Use cases:** -- ตรวจแก้จุดบกพร่องว่าทำไมการรวมไคลเอนต์/ผู้ให้บริการเฉพาะจึงล้มเหลว -- ตรวจสอบว่าแท็กการคิด การเรียกใช้เครื่องมือ และการแจ้งเตือนของระบบแปลอย่างถูกต้อง -- เปรียบเทียบความแตกต่างของรูปแบบระหว่างรูปแบบ OpenAI, Claude, Gemini และ Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### กลยุทธ์การกำหนดเส้นทาง +### Routing Strategies -กำหนดค่าผ่าน **แดชบอร์ด → การตั้งค่า → การกำหนดเส้นทาง** +Configure via **Dashboard → Settings → Routing**. -| กลยุทธ์ | คำอธิบาย | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| **กรอกก่อน** | ใช้บัญชีตามลำดับความสำคัญ — บัญชีหลักจะจัดการคำขอทั้งหมดจนกว่าจะไม่พร้อมใช้งาน | -| **โรบินตัวกลม** | วนรอบบัญชีทั้งหมดด้วยขีดจำกัดที่กำหนดได้ (ค่าเริ่มต้น: 3 สายต่อบัญชี) | -| **P2C (พลังสองตัวเลือก)** | เลือกบัญชีและเส้นทางแบบสุ่ม 2 บัญชีไปยังบัญชีที่ดีต่อสุขภาพมากขึ้น — สร้างสมดุลระหว่างภาระกับการรับรู้เรื่องสุขภาพ | -| **สุ่ม** | สุ่มเลือกบัญชีสำหรับแต่ละคำขอโดยใช้ Fisher-Yates shuffle | -| **ใช้น้อยที่สุด** | กำหนดเส้นทางไปยังบัญชีที่มีการประทับเวลา `lastUsedAt` เก่าที่สุด กระจายการรับส่งข้อมูลเท่าๆ กัน | -| **ปรับต้นทุนให้เหมาะสม** | กำหนดเส้นทางไปยังบัญชีที่มีค่าลำดับความสำคัญต่ำสุด ปรับให้เหมาะสมสำหรับผู้ให้บริการที่มีต้นทุนต่ำที่สุด | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### นามแฝงโมเดลไวด์การ์ด +#### Wildcard Model Aliases -สร้างรูปแบบไวด์การ์ดเพื่อทำการแมปชื่อโมเดลใหม่: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Wildcard รองรับ `*` (อักขระใดก็ได้) และ `?` (อักขระเดี่ยว) +Wildcards support `*` (any characters) and `?` (single character). -#### โซ่สำรอง +#### Fallback Chains -กำหนดห่วงโซ่ทางเลือกส่วนกลางที่ใช้กับคำขอทั้งหมด: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -542,46 +602,46 @@ Chain: production-fallback --- -### ความยืดหยุ่นและเซอร์กิตเบรกเกอร์ +### Resilience & Circuit Breakers -กำหนดค่าผ่าน **แดชบอร์ด → การตั้งค่า → ความยืดหยุ่น** +Configure via **Dashboard → Settings → Resilience**. -OmniRoute ใช้ความยืดหยุ่นระดับผู้ให้บริการด้วยองค์ประกอบสี่ประการ: +OmniRoute implements provider-level resilience with four components: -1. **โปรไฟล์ผู้ให้บริการ** — การกำหนดค่าต่อผู้ให้บริการสำหรับ: - - เกณฑ์ความล้มเหลว (จำนวนความล้มเหลวก่อนเปิด) - - ระยะเวลาคูลดาวน์ - - ความไวในการตรวจจับขีด จำกัด อัตรา - - พารามิเตอร์แบ็คออฟเอ็กซ์โปเนนเชียล +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **ขีดจำกัดอัตราที่แก้ไขได้** — ค่าเริ่มต้นระดับระบบที่กำหนดค่าได้ในแดชบอร์ด: - - **คำขอต่อนาที (RPM)** — คำขอสูงสุดต่อนาทีต่อบัญชี - - **เวลาขั้นต่ำระหว่างคำขอ** — ช่องว่างขั้นต่ำเป็นมิลลิวินาทีระหว่างคำขอ - - **คำขอพร้อมกันสูงสุด** — คำขอพร้อมกันสูงสุดต่อบัญชี - - คลิก **แก้ไข** เพื่อแก้ไข จากนั้น **บันทึก** หรือ **ยกเลิก** ค่ายังคงมีอยู่ผ่าน API ความยืดหยุ่น +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **เซอร์กิตเบรกเกอร์** — ติดตามความล้มเหลวของผู้ให้บริการแต่ละราย และเปิดวงจรโดยอัตโนมัติเมื่อถึงเกณฑ์: - - **ปิด** (สมบูรณ์) — คำขอดำเนินไปตามปกติ - - **เปิด** — ผู้ให้บริการถูกบล็อกชั่วคราวหลังจากเกิดข้อผิดพลาดซ้ำแล้วซ้ำอีก - - **HALF_OPEN** — ทดสอบว่าผู้ให้บริการฟื้นตัวหรือไม่ +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **นโยบายและตัวระบุที่ถูกล็อค** — แสดงสถานะเซอร์กิตเบรกเกอร์และตัวระบุที่ถูกล็อคพร้อมความสามารถในการบังคับปลดล็อค +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **การตรวจจับขีดจำกัดอัตราอัตโนมัติ** — ตรวจสอบส่วนหัว `429` และ `Retry-After` เพื่อหลีกเลี่ยงไม่ให้ถึงขีดจำกัดอัตราของผู้ให้บริการในเชิงรุก +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**เคล็ดลับสำหรับมือโปร:** ใช้ปุ่ม **รีเซ็ตทั้งหมด** เพื่อล้างเซอร์กิตเบรกเกอร์และคูลดาวน์ทั้งหมดเมื่อผู้ให้บริการฟื้นตัวจากการหยุดทำงาน +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### ส่งออก / นำเข้าฐานข้อมูล +### Database Export / Import -จัดการการสำรองฐานข้อมูลใน **แดชบอร์ด → การตั้งค่า → ระบบและที่เก็บข้อมูล** +Manage database backups in **Dashboard → Settings → System & Storage**. -| การกระทำ | คำอธิบาย | -| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| **ฐานข้อมูลการส่งออก** | ดาวน์โหลดฐานข้อมูล SQLite ปัจจุบันเป็นไฟล์ `.sqlite` | -| **ส่งออกทั้งหมด (.tar.gz)** | ดาวน์โหลดไฟล์เก็บถาวรการสำรองข้อมูลแบบเต็ม รวมถึง: ฐานข้อมูล การตั้งค่า คอมโบ การเชื่อมต่อของผู้ให้บริการ (ไม่มีข้อมูลประจำตัว) ข้อมูลเมตาของคีย์ API | -| **นำเข้าฐานข้อมูล** | อัปโหลดไฟล์ `.sqlite` เพื่อแทนที่ฐานข้อมูลปัจจุบัน การสำรองข้อมูลก่อนนำเข้าจะถูกสร้างขึ้นโดยอัตโนมัติ | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -595,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**การตรวจสอบการนำเข้า:** ไฟล์ที่นำเข้าได้รับการตรวจสอบความถูกต้อง (การตรวจสอบ SQLite Pragma), ตารางที่จำเป็น (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) และขนาด (สูงสุด 100MB) +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**กรณีการใช้งาน:** +**Use Cases:** -- โยกย้าย OmniRoute ระหว่างเครื่อง -- สร้างการสำรองข้อมูลภายนอกสำหรับการกู้คืนระบบ -- แบ่งปันการกำหนดค่าระหว่างสมาชิกในทีม (ส่งออกทั้งหมด → แชร์ไฟล์เก็บถาวร) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### แดชบอร์ดการตั้งค่า +### Settings Dashboard -หน้าการตั้งค่าแบ่งออกเป็น 5 แท็บเพื่อให้ง่ายต่อการนำทาง: +The settings page is organized into 5 tabs for easy navigation: -| แท็บ | สารบัญ | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| **ความปลอดภัย** | การตั้งค่าการเข้าสู่ระบบ/รหัสผ่าน, การควบคุมการเข้าถึง IP, การตรวจสอบสิทธิ์ API สำหรับ `/models` และการบล็อกผู้ให้บริการ | -| **การกำหนดเส้นทาง** | กลยุทธ์การกำหนดเส้นทางทั่วโลก (6 ตัวเลือก), นามแฝงโมเดลไวด์การ์ด, เชนทางเลือก, ค่าเริ่มต้นคอมโบ | -| **ความยืดหยุ่น** | โปรไฟล์ผู้ให้บริการ ขีดจำกัดอัตราที่แก้ไขได้ สถานะเซอร์กิตเบรกเกอร์ นโยบาย และตัวระบุที่ถูกล็อค | -| **เอไอ** | คิดการกำหนดค่างบประมาณ, การแทรกพร้อมท์ของระบบทั่วโลก, สถิติแคชพร้อมต์ | -| **ขั้นสูง** | การกำหนดค่าพร็อกซีส่วนกลาง (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### ต้นทุนและการจัดการงบประมาณ +### Costs & Budget Management -เข้าถึงได้ผ่าน **แดชบอร์ด → ค่าใช้จ่าย** +Access via **Dashboard → Costs**. -| แท็บ | วัตถุประสงค์ | -| ------------ | ------------------------------------------------------------------------------------------------- | -| **งบประมาณ** | กำหนดขีดจำกัดการใช้จ่ายต่อคีย์ API ด้วยงบประมาณรายวัน/รายสัปดาห์/รายเดือนและการติดตามแบบเรียลไทม์ | -| **ราคา** | ดูและแก้ไขรายการการกำหนดราคาโมเดล — ต้นทุนต่อโทเค็นอินพุต/เอาท์พุต 1K ต่อผู้ให้บริการ | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -638,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**การติดตามต้นทุน:** ทุกคำขอจะบันทึกการใช้โทเค็นและคำนวณต้นทุนโดยใช้ตารางราคา ดูรายละเอียดใน **แดชบอร์ด → การใช้งาน** ตามผู้ให้บริการ รุ่น และคีย์ API +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### การถอดเสียง +### Audio Transcription -OmniRoute รองรับการถอดเสียงผ่านปลายทางที่เข้ากันได้กับ OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -658,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -ผู้ให้บริการที่มีอยู่: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`) +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -รูปแบบเสียงที่รองรับ: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### กลยุทธ์การปรับสมดุลคอมโบ +### Combo Balancing Strategies -กำหนดค่าการปรับสมดุลต่อคอมโบใน **แดชบอร์ด → คอมโบ → สร้าง/แก้ไข → กลยุทธ์** +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| กลยุทธ์ | คำอธิบาย | -| ----------------------------- | -------------------------------------------------------------- | -| **โรบินตัวกลม** | หมุนเวียนไปตามโมเดลต่างๆ ตามลำดับ | -| **ลำดับความสำคัญ** | ลองใช้โมเดลแรกเสมอ ถอยกลับเฉพาะข้อผิดพลาด | -| **สุ่ม** | เลือกโมเดลแบบสุ่มจากคอมโบสำหรับแต่ละคำขอ | -| **ถ่วงน้ำหนัก** | เส้นทางตามสัดส่วนตามน้ำหนักที่กำหนดต่อรุ่น | -| **ใช้งานน้อยที่สุด** | กำหนดเส้นทางไปยังโมเดลที่มีคำขอล่าสุดน้อยที่สุด (ใช้เมตริกผสม) | -| **การเพิ่มประสิทธิภาพต้นทุน** | เส้นทางไปยังรุ่นที่ถูกที่สุด (ใช้ตารางราคา) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -ค่าเริ่มต้นคอมโบสากลสามารถตั้งค่าได้ใน **แดชบอร์ด → การตั้งค่า → การกำหนดเส้นทาง → ค่าเริ่มต้นคอมโบ** +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### แดชบอร์ดสุขภาพ +### Health Dashboard -เข้าถึงได้ทาง **Dashboard → Health** ภาพรวมความสมบูรณ์ของระบบเรียลไทม์พร้อมการ์ด 6 ใบ: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| บัตร | มันแสดงอะไร | -| ----------------------------- | ---------------------------------------------------------------- | -| **สถานะระบบ** | สถานะการออนไลน์ เวอร์ชัน การใช้หน่วยความจำ ไดเร็กทอรีข้อมูล | -| **สุขภาพของผู้ให้บริการ** | สถานะเซอร์กิตเบรกเกอร์ต่อผู้ให้บริการ (ปิด/เปิด/เปิดครึ่ง) | -| **จำกัดอัตรา** | คูลดาวน์จำกัดอัตราที่ใช้งานอยู่ต่อบัญชีพร้อมเวลาที่เหลืออยู่ | -| **การล็อกที่ใช้งานอยู่** | ผู้ให้บริการถูกบล็อกชั่วคราวโดยนโยบายการล็อค | -| **แคชลายเซ็น** | สถิติแคชการขจัดข้อมูลซ้ำซ้อน (คีย์ที่ใช้งานอยู่ อัตราการเข้าถึง) | -| **การวัดระยะไกลแบบหน่วงเวลา** | การรวมเวลาแฝง p50/p95/p99 ต่อผู้ให้บริการ | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**เคล็ดลับสำหรับมือโปร:** หน้าสุขภาพจะรีเฟรชอัตโนมัติทุกๆ 10 วินาที ใช้การ์ดเซอร์กิตเบรกเกอร์เพื่อระบุว่าผู้ให้บริการรายใดกำลังประสบปัญหา +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/uk-UA/API_REFERENCE.md b/docs/i18n/uk-UA/API_REFERENCE.md index ba5fd8b915..b795722c11 100644 --- a/docs/i18n/uk-UA/API_REFERENCE.md +++ b/docs/i18n/uk-UA/API_REFERENCE.md @@ -1,12 +1,12 @@ # API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Повний довідник для всіх кінцевих точок OmniRoute API. +Complete reference for all OmniRoute API endpoints. --- -## Зміст +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## Завершення чату +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Спеціальні заголовки +### Custom Headers -| Заголовок | Напрям | Опис | -| ------------------------ | --------- | --------------------------------------- | -| `X-OmniRoute-No-Cache` | Запит | Установіть `true`, щоб обійти кеш | -| `X-OmniRoute-Progress` | Запит | Встановіть `true` для подій прогресу | -| `Idempotency-Key` | Запит | Ключ дедуплювання (5-секундне вікно) | -| `X-Request-Id` | Запит | Альтернативний ключ дедуплювання | -| `X-OmniRoute-Cache` | Відповідь | `HIT` або `MISS` (не потоковий) | -| `X-OmniRoute-Idempotent` | Відповідь | `true` якщо дедупліковано | -| `X-OmniRoute-Progress` | Відповідь | `enabled`, якщо відстеження прогресу на | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Вбудовування +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Доступні постачальники: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Генерація зображень +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Доступні постачальники: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Список моделей +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Кінцеві точки сумісності +## Compatibility Endpoints -| Метод | Шлях | Формат | -| ------------ | --------------------------- | ---------------------- | -| Опублікувати | `/v1/chat/completions` | OpenAI | -| Опублікувати | `/v1/messages` | Антропний | -| Опублікувати | `/v1/responses` | Відповіді OpenAI | -| Опублікувати | `/v1/embeddings` | OpenAI | -| Опублікувати | `/v1/images/generations` | OpenAI | -| ОТРИМАТИ | `/v1/models` | OpenAI | -| Опублікувати | `/v1/messages/count_tokens` | Антропний | -| ОТРИМАТИ | `/v1beta/models` | Близнюки | -| Опублікувати | `/v1beta/models/{...path}` | Gemini generateContent | -| Опублікувати | `/v1/api/chat` | Оллама | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Виділені маршрути постачальників +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Префікс провайдера додається автоматично, якщо його немає. Невідповідні моделі повертають `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Семантичний кеш +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Приклад відповіді: +Response example: ```json { @@ -162,154 +162,164 @@ DELETE /api/cache --- -## Інформаційна панель і керування +## Dashboard & Management -### Автентифікація +### Authentication -| Кінцева точка | Метод | Опис | -| ----------------------------- | ------------ | -------------------------- | -| `/api/auth/login` | Опублікувати | Вхід | -| `/api/auth/logout` | Опублікувати | Вийти | -| `/api/settings/require-login` | GET/PUT | Перемкнути необхідний вхід | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Керування провайдером +### Provider Management -| Кінцева точка | Метод | Опис | -| ---------------------------- | --------------- | ------------------------------------ | -| `/api/providers` | GET/POST | Список / створення постачальників | -| `/api/providers/[id]` | GET/PUT/DELETE | Керувати постачальником | -| `/api/providers/[id]/test` | Опублікувати | Перевірте підключення провайдера | -| `/api/providers/[id]/models` | ОТРИМАТИ | Список моделей провайдерів | -| `/api/providers/validate` | Опублікувати | Перевірте конфігурацію постачальника | -| `/api/provider-nodes*` | Різні | Керування вузлом провайдера | -| `/api/provider-models` | GET/POST/DELETE | Індивідуальні моделі | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Потоки OAuth +### OAuth Flows -| Кінцева точка | Метод | Опис | -| -------------------------------- | ----- | ----------------------- | -| `/api/oauth/[provider]/[action]` | Різні | OAuth для постачальника | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Маршрутизація та конфігурація +### Routing & Config -| Кінцева точка | Метод | Опис | -| --------------------- | -------- | ------------------------------- | -| `/api/models/alias` | GET/POST | Псевдоніми моделей | -| `/api/models/catalog` | ОТРИМАТИ | Всі моделі за провайдером + тип | -| `/api/combos*` | Різні | Комбо управління | -| `/api/keys*` | Різні | Керування ключами API | -| `/api/pricing` | ОТРИМАТИ | Модель ціноутворення | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Використання та аналітика +### Usage & Analytics -| Кінцева точка | Метод | Опис | -| --------------------------- | -------- | -------------------------------- | -| `/api/usage/history` | ОТРИМАТИ | Історія використання | -| `/api/usage/logs` | ОТРИМАТИ | Журнали використання | -| `/api/usage/request-logs` | ОТРИМАТИ | Журнали рівня запиту | -| `/api/usage/[connectionId]` | ОТРИМАТИ | Використання кожного підключення | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Налаштування +### Settings -| Кінцева точка | Метод | Опис | -| ------------------------------- | ------------ | ------------------------------- | -| `/api/settings` | GET/PUT | Загальні налаштування | -| `/api/settings/proxy` | GET/PUT | Конфігурація мережевого проксі | -| `/api/settings/proxy/test` | Опублікувати | Тест проксі-з'єднання | -| `/api/settings/ip-filter` | GET/PUT | Список дозволених/чорних IP | -| `/api/settings/thinking-budget` | GET/PUT | Обґрунтування жетонного бюджету | -| `/api/settings/system-prompt` | GET/PUT | Глобальна системна підказка | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Моніторинг +### Monitoring -| Кінцева точка | Метод | Опис | -| ------------------------ | ----------------- | -------------------------------- | -| `/api/sessions` | ОТРИМАТИ | Відстеження активної сесії | -| `/api/rate-limits` | ОТРИМАТИ | Ліміти ставок за обліковий запис | -| `/api/monitoring/health` | ОТРИМАТИ | Перевірка стану здоров'я | -| `/api/cache` | ОТРИМАТИ/ВИДАЛИТИ | Статистика кешу / очищення | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Резервне копіювання та експорт/імпорт +### Backup & Export/Import -| Кінцева точка | Метод | Опис | -| --------------------------- | ------------ | ------------------------------------------------ | -| `/api/db-backups` | ОТРИМАТИ | Список доступних резервних копій | -| `/api/db-backups` | ПОСТАВИТИ | Створіть резервну копію вручну | -| `/api/db-backups` | Опублікувати | Відновити з певної резервної копії | -| `/api/db-backups/export` | ОТРИМАТИ | Завантажити базу даних як файл .sqlite | -| `/api/db-backups/import` | Опублікувати | Завантажте файл .sqlite для заміни бази даних | -| `/api/db-backups/exportAll` | ОТРИМАТИ | Завантажте повну резервну копію як архів .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Хмарна синхронізація +### Cloud Sync -| Кінцева точка | Метод | Опис | -| ---------------------- | ------------ | ------------------------------ | -| `/api/sync/cloud` | Різні | Операції хмарної синхронізації | -| `/api/sync/initialize` | Опублікувати | Ініціалізація синхронізації | -| `/api/cloud/*` | Різні | Управління хмарою | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Інструменти CLI +### CLI Tools -| Кінцева точка | Метод | Опис | -| ---------------------------------- | -------- | --------------------------------- | -| `/api/cli-tools/claude-settings` | ОТРИМАТИ | Клод CLI статус | -| `/api/cli-tools/codex-settings` | ОТРИМАТИ | Codex CLI status | -| `/api/cli-tools/droid-settings` | ОТРИМАТИ | Droid CLI status | -| `/api/cli-tools/openclaw-settings` | ОТРИМАТИ | Статус OpenClaw CLI | -| `/api/cli-tools/runtime/[toolId]` | ОТРИМАТИ | Загальне середовище виконання CLI | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Відповіді CLI включають: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Стійкість і обмеження швидкості +### ACP Agents -| Кінцева точка | Метод | Опис | -| ----------------------- | ------------ | -------------------------------------------- | -| `/api/resilience` | GET/PUT | Отримати/оновити профілі стійкості | -| `/api/resilience/reset` | Опублікувати | Скидання автоматичних вимикачів | -| `/api/rate-limits` | ОТРИМАТИ | Статус обмеження ставки на обліковий запис | -| `/api/rate-limit` | ОТРИМАТИ | Конфігурація глобального обмеження швидкості | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Оцінки +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Кінцева точка | Метод | Опис | -| ------------- | -------- | ---------------------------------------------- | -| `/api/evals` | GET/POST | Створити список eval suites / запустити оцінку | +### Resilience & Rate Limits -### Політика +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Кінцева точка | Метод | Опис | -| --------------- | --------------- | --------------------------------- | -| `/api/policies` | GET/POST/DELETE | Керування політикою маршрутизації | +### Evals -### Відповідність +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Кінцева точка | Метод | Опис | -| --------------------------- | -------- | ---------------------------------------- | -| `/api/compliance/audit-log` | ОТРИМАТИ | Журнал аудиту відповідності (останній N) | +### Policies -### v1beta (сумісний із Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Кінцева точка | Метод | Опис | -| -------------------------- | ------------ | -------------------------------------- | -| `/v1beta/models` | ОТРИМАТИ | Список моделей у форматі Gemini | -| `/v1beta/models/{...path}` | Опублікувати | Кінцева точка Gemini `generateContent` | +### Compliance -Ці кінцеві точки відображають формат API Gemini для клієнтів, які очікують нативної сумісності з Gemini SDK. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### Внутрішні/системні API +### v1beta (Gemini-Compatible) -| Кінцева точка | Метод | Опис | -| --------------- | ------------ | --------------------------------------------------------------------------- | -| `/api/init` | ОТРИМАТИ | Перевірка ініціалізації програми (використовується під час першого запуску) | -| `/api/tags` | ОТРИМАТИ | Сумісні з Ollama теги моделей (для клієнтів Ollama) | -| `/api/restart` | Опублікувати | Ініціювати плавний перезапуск сервера | -| `/api/shutdown` | Опублікувати | Ініціювати плавне завершення роботи сервера | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Примітка.** Ці кінцеві точки використовуються внутрішньо системою або для сумісності клієнта Ollama. Зазвичай вони не викликаються кінцевими користувачами. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Транскрипція аудіо +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Транскрибуйте аудіофайли за допомогою Deepgram або AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Запит:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Відповідь:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Підтримувані постачальники:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Підтримувані формати:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Сумісність Ollama +## Ollama Compatibility -Для клієнтів, які використовують формат API Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Запити автоматично перекладаються між Ollama та внутрішніми форматами. +Requests are automatically translated between Ollama and internal formats. --- -## Телеметрія +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Відповідь:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Бюджет +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Наявність моделі +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Обробка запиту +## Request Processing -1. Клієнт надсилає запит на `/v1/*` -2. Обробник маршруту викликає `handleChat`, `handleEmbedding`, `handleAudioTranscription` або `handleImageGeneration` -3. Модель вирішено (прямий постачальник/модель або псевдонім/комбо) -4. Облікові дані, вибрані з локальної БД з фільтрацією доступності облікових записів -5. Для чату: `handleChatCore` — визначення формату, переклад, перевірка кешу, перевірка ідемпотентності -6. Виконавець провайдера надсилає висхідний запит -7. Відповідь перекладається назад у формат клієнта (чат) або повертається як є (вбудовування/зображення/аудіо) -8. Запис використання/реєстрації -9. Резервний варіант застосовується до помилок відповідно до правил комбінування +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Повне посилання на архітектуру: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Автентифікація +## Authentication -- Маршрути інформаційної панелі (`/dashboard/*`) використовують `auth_token` cookie -- Вхід використовує збережений хеш пароля; повернутися до `INITIAL_PASSWORD` -- `requireLogin` можна перемикати через `/api/settings/require-login` -- Маршрути `/v1/*` додатково вимагають ключ API носія, коли `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/uk-UA/ARCHITECTURE.md b/docs/i18n/uk-UA/ARCHITECTURE.md index 574b9364bd..258d62df53 100644 --- a/docs/i18n/uk-UA/ARCHITECTURE.md +++ b/docs/i18n/uk-UA/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Архітектура OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Останнє оновлення: 2026-02-18_ +_Last updated: 2026-03-04_ -## Резюме +## Executive Summary -OmniRoute — це локальний шлюз штучного інтелекту та інформаційна панель, побудована на Next.js. -Він надає єдину кінцеву точку, сумісну з OpenAI (`/v1/*`), і направляє трафік між декількома вихідними постачальниками з перекладом, резервним варіантом, оновленням маркерів і відстеженням використання. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Основні можливості: +Core capabilities: -- OpenAI-сумісна поверхня API для CLI/інструментів (28 постачальників) -- Переклад запитів/відповідей між форматами постачальників -- Запасна комбінована модель (багатомодельна послідовність) -- Запасний варіант на рівні облікового запису (декілька облікових записів на постачальника) -- OAuth + API-ключ управління підключенням провайдера -- Генерація вбудовування через `/v1/embeddings` (6 провайдерів, 9 моделей) -- Генерація зображення через `/v1/images/generations` (4 постачальники, 9 моделей) -- Аналіз тегів мислення (`...`) для моделей міркування - — Дезінфекція відповіді для суворої сумісності з OpenAI SDK - — Нормалізація ролі (розробник→система, система→користувач) для сумісності між постачальниками -- Перетворення структурованого виводу (json_schema → Gemini responseSchema) -- Локальна постійність для провайдерів, ключів, псевдонімів, комбо, налаштувань, ціноутворення -- Відстеження використання/вартості та реєстрація запитів -- Додаткова хмарна синхронізація для синхронізації кількох пристроїв/станів - — Список дозволених/чорних IP-адрес для контролю доступу до API -- Продумане управління бюджетом (прохідний/автоматичний/спеціальний/адаптивний) -- Оперативна ін'єкція глобальної системи -- Відстеження сесії та відбитки пальців -- Розширене обмеження швидкості для кожного облікового запису за допомогою профілів постачальника -- Схема автоматичного вимикача для стійкості провайдера -- Захист стада від грому з блокуванням м'ютексу - — Кеш дедуплікації запитів на основі підпису -- Рівень домену: доступність моделі, правила вартості, резервна політика, політика блокування -- Постійність стану домену (скрізний кеш SQLite для резервних копій, бюджетів, блокувань, автоматичних вимикачів) -- Механізм політики для централізованої оцінки запитів (блокування → бюджет → резервний варіант) -- Запит телеметрії з агрегацією затримок p50/p95/p99 -- Ідентифікатор кореляції (X-Request-Id) для наскрізного відстеження -- Журнал аудиту відповідності з відмовою для кожного ключа API -- Eval framework для забезпечення якості LLM - — Панель інструментів інтерфейсу Resilience зі статусом автоматичного вимикача в режимі реального часу -- Модульні постачальники OAuth (12 окремих модулів під `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Основна модель середовища виконання: +Primary runtime model: -- Маршрути програми Next.js під `src/app/api/*` реалізують як API панелі керування, так і API сумісності -- Спільне ядро SSE/маршрутизації в `src/sse/*` + `open-sse/*` обробляє виконання провайдера, переклад, потокове передавання, відкат і використання +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Обсяг і межі +## Scope and Boundaries -### У межах +### In Scope -- Час виконання локального шлюзу -- API керування інформаційною панеллю -- Автентифікація постачальника та оновлення маркера -- Запит на переклад і потокове передавання SSE - — Локальний стан + постійність використання - — Додаткова синхронізація з хмарою +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Поза межами +### Out of Scope -- Реалізація хмарної служби за `NEXT_PUBLIC_CLOUD_URL` -- Площина SLA/контроль постачальника поза локальним процесом -- Самі зовнішні двійкові файли CLI (Claude CLI, Codex CLI тощо) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Системний контекст високого рівня +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Основні компоненти середовища виконання +## Core Runtime Components -## 1) API та рівень маршрутизації (маршрути програми Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Основні каталоги: +Main directories: -- `src/app/api/v1/*` та `src/app/api/v1beta/*` для API сумісності -- `src/app/api/*` для API керування/конфігурації -- Далі перезаписує в `next.config.mjs` карту `/v1/*` на `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Важливі маршрути сумісності: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — включає власні моделі з `custom: true` -- `src/app/api/v1/embeddings/route.ts` — генерація вбудовування (6 провайдерів) -- `src/app/api/v1/images/generations/route.ts` — генерація зображень (4+ провайдери вкл. Antigravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — спеціальний чат для кожного провайдера -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — виділені вбудовування для кожного постачальника -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — виділені зображення для кожного постачальника +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Домени керування: +Management domains: -- Аутентифікація/налаштування: `src/app/api/auth/*`, `src/app/api/settings/*` -- Постачальники/підключення: `src/app/api/providers*` -- Вузли постачальника: `src/app/api/provider-nodes*` -- Спеціальні моделі: `src/app/api/provider-models` (GET/POST/DELETE) -- Каталог моделей: `src/app/api/models/catalog` (GET) -- Конфігурація проксі: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Ключі/псевдоніми/комбінації/ціни: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Використання: `src/app/api/usage/*` -- Синхронізація/хмара: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Допоміжні інструменти CLI: `src/app/api/cli-tools/*` -- IP-фільтр: `src/app/api/settings/ip-filter` (GET/PUT) -- Бюджет мислення: `src/app/api/settings/thinking-budget` (GET/PUT) -- Системне повідомлення: `src/app/api/settings/system-prompt` (GET/PUT) -- Сеанси: `src/app/api/sessions` (ОТРИМАТИ) -- Обмеження швидкості: `src/app/api/rate-limits` (GET) -- Стійкість: `src/app/api/resilience` (GET/PATCH) — профілі постачальників, автоматичний вимикач, граничний стан швидкості -- Скидання стійкості: `src/app/api/resilience/reset` (POST) — скидання вимикачів + відновлення -- Статистика кешу: `src/app/api/cache/stats` (GET/DELETE) -- Доступність моделі: `src/app/api/models/availability` (GET/POST) -- Телеметрія: `src/app/api/telemetry/summary` (GET) -- Бюджет: `src/app/api/usage/budget` (GET/POST) -- Резервні ланцюжки: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Аудит відповідності: `src/app/api/compliance/audit-log` (GET) -- Оцінки: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Правила: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) ## 2) SSE + Translation Core -Основні модулі потоку: +Main flow modules: -- Запис: `src/sse/handlers/chat.ts` -- Оркестровка ядра: `open-sse/handlers/chatCore.ts` -- Адаптери виконання постачальника: `open-sse/executors/*` -- Виявлення формату/конфігурація постачальника: `open-sse/services/provider.ts` -- Розбір/вирішення моделі: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Резервна логіка облікового запису: `open-sse/services/accountFallback.ts` -- Реєстр перекладів: `open-sse/translator/index.ts` -- Трансформації потоку: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Вилучення/нормалізація використання: `open-sse/utils/usageTracking.ts` -- Розбір тегів Think: `open-sse/utils/thinkTagParser.ts` -- Обробник вбудовування: `open-sse/handlers/embeddings.ts` -- Реєстр постачальника вбудовування: `open-sse/config/embeddingRegistry.ts` -- Обробник створення зображення: `open-sse/handlers/imageGeneration.ts` -- Реєстр постачальників зображень: `open-sse/config/imageRegistry.ts` -- Дезінфекція відповіді: `open-sse/handlers/responseSanitizer.ts` -- Нормалізація ролі: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Послуги (бізнес-логіка): +Services (business logic): -- Вибір облікового запису/оцінка: `open-sse/services/accountSelector.ts` -- Керування життєвим циклом контексту: `open-sse/services/contextManager.ts` -- Примусовий IP-фільтр: `open-sse/services/ipFilter.ts` -- Відстеження сесії: `open-sse/services/sessionManager.ts` -- Запит на дедуплікацію: `open-sse/services/signatureCache.ts` -- Системна підказка: `open-sse/services/systemPrompt.ts` -- Продумане управління бюджетом: `open-sse/services/thinkingBudget.ts` -- Маршрутизація моделі підстановок: `open-sse/services/wildcardRouter.ts` -- Керування обмеженнями швидкості: `open-sse/services/rateLimitManager.ts` -- Автоматичний вимикач: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Модулі рівня домену: +Domain layer modules: -- Доступність моделі: `src/lib/domain/modelAvailability.ts` -- Правила витрат/бюджети: `src/lib/domain/costRules.ts` -- Резервна політика: `src/lib/domain/fallbackPolicy.ts` -- Комбінований розпізнавач: `src/lib/domain/comboResolver.ts` -- Політика блокування: `src/lib/domain/lockoutPolicy.ts` -- Механізм політики: `src/domain/policyEngine.ts` — централізоване блокування → бюджет → резервна оцінка -- Каталог кодів помилок: `src/lib/domain/errorCodes.ts` -- Ідентифікатор запиту: `src/lib/domain/requestId.ts` -- Час очікування отримання: `src/lib/domain/fetchTimeout.ts` -- Запит телеметрії: `src/lib/domain/requestTelemetry.ts` -- Відповідність/аудит: `src/lib/domain/compliance/index.ts` +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` - Eval runner: `src/lib/domain/evalRunner.ts` -- Постійність стану домену: `src/lib/db/domainState.ts` — SQLite CRUD для резервних ланцюжків, бюджетів, історії витрат, стану блокування, автоматичних вимикачів +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Модулі постачальника OAuth (12 окремих файлів під `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Індекс реєстру: `src/lib/oauth/providers/index.ts` -- Окремі постачальники: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Тонка оболонка: `src/lib/oauth/providers.ts` — реекспорт з окремих модулів +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Рівень стійкості +## 3) Persistence Layer -База даних первинного стану: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- файл: `${DATA_DIR}/db.json` (або `$XDG_CONFIG_HOME/omniroute/db.json`, якщо встановлено, інакше `~/.omniroute/db.json`) -- сутності: providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -БД використання: +Usage persistence: -- `src/lib/usageDb.ts` -- файли: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- дотримується тієї ж базової політики каталогу, що й `localDb` (`DATA_DIR`, потім `XDG_CONFIG_HOME/omniroute`, якщо встановлено) -- розкладено на підмодулі: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -БД стану домену (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — операції CRUD для стану домену -- Таблиці (створені в `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Шаблон кешу наскрізного запису: Карти в пам'яті є авторитетними під час виконання; мутації записуються синхронно в SQLite; стан відновлюється з БД при холодному запуску +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start ## 4) Auth + Security Surfaces -- Автентифікація файлів cookie інформаційної панелі: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Генерація/перевірка ключа API: `src/shared/utils/apiKey.ts` -- Секрети постачальника зберігаються в `providerConnections` записах -- Підтримка вихідного проксі-сервера через `open-sse/utils/proxyFetch.ts` (env vars) і `open-sse/utils/networkProxy.ts` (налаштовується для кожного постачальника або глобально) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Хмарна синхронізація +## 5) Cloud Sync -- Ініціалізація планувальника: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Періодичне завдання: `src/shared/services/cloudSyncScheduler.ts` -- Контрольний маршрут: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Життєвий цикл запиту (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Потік резервного облікового запису +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Резервні рішення керуються `open-sse/services/accountFallback.ts` за допомогою кодів стану та евристики повідомлень про помилки. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Введення OAuth і життєвий цикл оновлення маркерів +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Оновлення під час живого трафіку виконується всередині `open-sse/handlers/chatCore.ts` через виконавець `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Життєвий цикл Cloud Sync (Увімкнути / Синхронізувати / Вимкнути) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Періодичну синхронізацію запускає `CloudSyncScheduler`, коли хмару ввімкнено. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Модель даних і карта зберігання +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Файли фізичного зберігання: +Physical storage files: -- основний стан: `${DATA_DIR}/db.json` (або `$XDG_CONFIG_HOME/omniroute/db.json`, якщо встановлено, інакше `~/.omniroute/db.json`) -- статистика використання: `${DATA_DIR}/usage.json` -- рядки журналу запитів: `${DATA_DIR}/log.txt` -- додатковий перекладач/сеанси налагодження запитів: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Топологія розгортання +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,242 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Відображення модулів (важливо для прийняття рішень) +## Module Mapping (Decision-Critical) -### Модулі маршруту та API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API сумісності -- `src/app/api/v1/providers/[provider]/*`: виділені маршрути для кожного постачальника (чат, вбудовування, зображення) -- `src/app/api/providers*`: CRUD провайдера, перевірка, тестування -- `src/app/api/provider-nodes*`: настроюване сумісне керування вузлом -- `src/app/api/provider-models`: користувацьке керування моделлю (CRUD) -- `src/app/api/models/catalog`: API каталогу повної моделі (усі типи згруповані за постачальником) -- `src/app/api/oauth/*`: потоки OAuth/код пристрою -- `src/app/api/keys*`: життєвий цикл локального ключа API -- `src/app/api/models/alias`: керування псевдонімами -- `src/app/api/combos*`: резервне керування комбо -- `src/app/api/pricing`: заміна ціноутворення для розрахунку вартості -- `src/app/api/settings/proxy`: конфігурація проксі (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: тест підключення вихідного проксі (POST) -- `src/app/api/usage/*`: API використання та журналів -- `src/app/api/sync/*` + `src/app/api/cloud/*`: хмарна синхронізація та помічники в хмарі -- `src/app/api/cli-tools/*`: локальні автори/перевірки конфігурації CLI -- `src/app/api/settings/ip-filter`: список дозволених/чорних IP-адрес (GET/PUT) -- `src/app/api/settings/thinking-budget`: конфігурація бюджету маркера мислення (GET/PUT) -- `src/app/api/settings/system-prompt`: глобальна системна підказка (GET/PUT) -- `src/app/api/sessions`: список активних сеансів (GET) -- `src/app/api/rate-limits`: статус ліміту ставки на обліковий запис (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Ядро маршрутизації та виконання +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: синтаксичний аналіз запиту, комбінована обробка, цикл вибору облікового запису -- `open-sse/handlers/chatCore.ts`: переклад, розсилка виконавця, обробка повторів/оновлень, налаштування потоку -- `open-sse/executors/*`: поведінка мережі та формату залежно від постачальника +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Реєстр перекладів і конвертери форматів +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: реєстр перекладачів і оркестровка -- Запит перекладачів: `open-sse/translator/request/*` -- Перекладачі відповідей: `open-sse/translator/response/*` -- Константи формату: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Наполегливість +### Persistence -- `src/lib/localDb.ts`: постійна конфігурація/стан -- `src/lib/usageDb.ts`: історія використання та журнали поточних запитів +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Покриття виконавця постачальника (шаблон стратегії) +## Provider Executor Coverage (Strategy Pattern) -Кожен постачальник має спеціалізований виконавець, що розширює `BaseExecutor` (у `open-sse/executors/base.ts`), який забезпечує побудову URL-адреси, побудову заголовка, повторну спробу з експоненційною відстрочкою, перехоплювачі оновлення облікових даних і метод оркестровки `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Виконавець | Постачальник(и) | Спеціальна обробка | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Конфігурація динамічної URL-адреси/заголовка для кожного постачальника | -| `AntigravityExecutor` | Антигравітація Google | Ідентифікатори користувацьких проектів/сеансів, повторна спроба після аналізу | -| `CodexExecutor` | OpenAI Codex | Впроваджує системні інструкції, змушує міркувати | -| `CursorExecutor` | Курсор IDE | Протокол ConnectRPC, кодування Protobuf, підпис запиту через контрольну суму | -| `GithubExecutor` | Копілот GitHub | Оновлення маркера Copilot, заголовки, що імітують VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Двійковий формат AWS EventStream → Перетворення SSE | -| `GeminiCLIExecutor` | Gemini CLI | Цикл оновлення маркера Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Усі інші постачальники (включно з настроюваними сумісними вузлами) використовують `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Матриця сумісності постачальників +## Provider Compatibility Matrix -| Постачальник | Формат | Авторизація | Потік | Непотоковий | Токен Оновити | Використання API | -| ---------------- | ---------------- | ---------------------- | ---------------- | ----------- | ------------- | ------------------------- | -| Клод | Клод | Ключ API / OAuth | ✅ | ✅ | ✅ | ⚠️ Лише адміністратор | -| Близнюки | близнюки | Ключ API / OAuth | ✅ | ✅ | ✅ | ⚠️ Хмарна консоль | -| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Хмарна консоль | -| Антигравітація | антигравітація | OAuth | ✅ | ✅ | ✅ | ✅ Повна квота API | -| OpenAI | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| Кодекс | openai-відповіді | OAuth | ✅ примусовий | ❌ | ✅ | ✅ Обмеження тарифів | -| Копілот GitHub | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Знімки квот | -| Курсор | курсор | Власна контрольна сума | ✅ | ✅ | ❌ | ❌ | -| Кіро | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Обмеження використання | -| Квен | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ За запитом | -| iFlow | openai | OAuth (базовий) | ✅ | ✅ | ✅ | ⚠️ За запитом | -| OpenRouter | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | Клод | Ключ API | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| Groq | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| xAI (Грок) | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| Містраль | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| Розгубленість | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| Разом AI | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| Феєрверк AI | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| Головний мозок | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| Cohere | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | openai | Ключ API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Покриття перекладу формату +## Format Translation Coverage -Виявлені вихідні формати включають: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Цільові формати включають: +Target formats include: -- Чат/Відповіді OpenAI -- Клод -- Gemini/Gemini-CLI/Антигравітаційна оболонка -- Кіро -- Курсор +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -Для перекладу використовується **OpenAI як центральний формат** — усі перетворення проходять через OpenAI як проміжний: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Переклади вибираються динамічно на основі форми вихідного корисного навантаження та цільового формату постачальника. +Translations are selected dynamically based on source payload shape and provider target format. -Додаткові рівні обробки в конвеєрі перекладу: +Additional processing layers in the translation pipeline: -- **Дезінфікація відповіді** — видаляє нестандартні поля з відповідей у форматі OpenAI (як потокових, так і не потокових), щоб забезпечити сувору відповідність SDK -- **Нормалізація ролі** — перетворює `developer` → `system` для цілей, що не є OpenAI; об’єднує `system` → `user` для моделей, які відхиляють системну роль (GLM, ERNIE) -- **Вилучення тегів мислення** — аналізує блоки `...` з вмісту в поле `reasoning_content` -- **Структурований вихід** — перетворює OpenAI `response_format.json_schema` на `responseMimeType` + `responseSchema` Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Підтримувані кінцеві точки API +## Supported API Endpoints -| Кінцева точка | Формат | Обробник | -| -------------------------------------------------- | --------------------- | ----------------------------------------------------------------- | -| `POST /v1/chat/completions` | Чат OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Повідомлення Клода | Той самий обробник (визначено автоматично) | -| `POST /v1/responses` | Відповіді OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Вбудовування OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Список моделей | Маршрут API | -| `POST /v1/images/generations` | Зображення OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Список моделей | Маршрут API | -| `POST /v1/providers/{provider}/chat/completions` | Чат OpenAI | Виділено для кожного постачальника з перевіркою моделі | -| `POST /v1/providers/{provider}/embeddings` | Вбудовування OpenAI | Виділено для кожного постачальника з перевіркою моделі | -| `POST /v1/providers/{provider}/images/generations` | Зображення OpenAI | Виділено для кожного постачальника з перевіркою моделі | -| `POST /v1/messages/count_tokens` | Клод Токен Підрахунок | Маршрут API | -| `GET /v1/models` | Список моделей OpenAI | Маршрут API (чат + вбудовування + зображення + спеціальні моделі) | -| `GET /api/models/catalog` | Каталог | Усі моделі згруповані за постачальником + тип | -| `POST /v1beta/models/*:streamGenerateContent` | Близнюки рідні | Маршрут API | -| `GET/PUT/DELETE /api/settings/proxy` | Конфігурація проксі | Налаштування мережевого проксі | -| `POST /api/settings/proxy/test` | З'єднання проксі | Кінцева точка перевірки справності/з’єднання проксі | -| `GET/POST/DELETE /api/provider-models` | Спеціальні моделі | Керування індивідуальною моделлю для кожного постачальника | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Обхідний обробник +## Bypass Handler -Обхідний обробник (`open-sse/utils/bypassHandler.ts`) перехоплює відомі запити на «викидання» від Claude CLI — пінг розігріву, вилучення заголовків і підрахунок токенів — і повертає **підроблену відповідь**, не споживаючи токени постачальника вищестоящих даних. Це спрацьовує лише тоді, коли `User-Agent` містить `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Конвеєр реєстратора запитів +## Request Logger Pipeline -Реєстратор запитів (`open-sse/utils/requestLogger.ts`) забезпечує 7-етапний конвеєр журналювання налагодження, вимкнений за замовчуванням, увімкнений через `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Файли записуються в `/logs//` для кожного сеансу запиту. +Files are written to `/logs//` for each request session. -## Режими відмов і стійкість +## Failure Modes and Resilience -## 1) Доступність облікового запису/постачальника +## 1) Account/Provider Availability -- час відновлення облікового запису постачальника через тимчасові помилки/помилки швидкості/автентифікації -- резервний обліковий запис перед невдалим запитом -- резервна комбінована модель, коли поточний шлях моделі/постачальника вичерпано +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Термін дії маркера +## 2) Token Expiry -- попередня перевірка та оновлення з повторною спробою для оновлюваних постачальників -- Повторна спроба 401/403 після спроби оновлення в основному шляху +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) Безпека потоку +## 3) Stream Safety -- контролер потоку з відключенням -- потік перекладу зі змивом у кінці потоку та обробкою `[DONE]` -- резервна оцінка використання, якщо метадані використання постачальника відсутні +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Деградація хмарної синхронізації +## 4) Cloud Sync Degradation -- виникають помилки синхронізації, але локальне виконання продовжується -- планувальник має логіку повторної спроби, але періодичне виконання наразі викликає синхронізацію з одноразовою спробою за замовчуванням +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Цілісність даних +## 5) Data Integrity -— Міграція/відновлення форми БД для відсутніх ключів +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -- пошкоджені гарантії скидання JSON для localDb і usageDb +## Observability and Operational Signals -## Спостережливість і робочі сигнали +Runtime visibility sources: -Джерела видимості під час виконання: +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -- журнали консолі від `src/sse/utils/logger.ts` -- сукупні дані про використання за запитом у `usage.json` -- текстовий журнал статусу запиту `log.txt` -- додаткові глибокі журнали запитів/перекладів під `logs/`, коли `ENABLE_REQUEST_LOGS=true` -- кінцеві точки використання інформаційної панелі (`/api/usage/*`) для використання інтерфейсу користувача +## Security-Sensitive Boundaries -## Чутливі до безпеки межі +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -- Секрет JWT (`JWT_SECRET`) захищає перевірку/підпис файлів cookie сеансу інструментальної панелі -- Початковий резервний пароль (`INITIAL_PASSWORD`, за замовчуванням `123456`) має бути перевизначений у реальних розгортаннях -- Ключ API HMAC Secret (`API_KEY_SECRET`) захищає згенерований локальний формат ключа API -- Секрети постачальника (ключі/токени API) зберігаються в локальній БД і повинні бути захищені на рівні файлової системи -- Кінцеві точки хмарної синхронізації покладаються на автентику ключа API + семантику ідентифікатора машини +## Environment and Runtime Matrix -## Середовище та матриця виконання +Environment variables actively used by code: -Змінні середовища, які активно використовуються кодом: +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -- Додаток/автентифікація: `JWT_SECRET`, `INITIAL_PASSWORD` -- Зберігання: `DATA_DIR` -- Сумісна поведінка вузла: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Перевизначення додаткової бази пам’яті (Linux/macOS, коли `DATA_DIR` не встановлено): `XDG_CONFIG_HOME` -- Хешування безпеки: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Журнал: `ENABLE_REQUEST_LOGS` -- URL-адреси синхронізації/хмари: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Вихідний проксі: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` та варіанти в нижньому регістрі -- Прапори функції SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Помічники платформи/виконання (не для конкретної програми): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +## Known Architectural Notes -## Відомі архітектурні примітки +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -1. `usageDb` та `localDb` тепер спільно використовують ту саму базову політику каталогу (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) із переміщенням файлів у старі версії. -2. `/api/v1/route.ts` повертає список статичних моделей і не є основним джерелом моделей, яке використовує `/v1/models`. -3. Реєстратор запитів записує повні заголовки/тіло, якщо ввімкнено; вважати каталог журналу конфіденційним. -4. Поведінка хмари залежить від правильності `NEXT_PUBLIC_BASE_URL` та доступності кінцевої точки хмари. -5. Каталог `open-sse/` опубліковано як `@omniroute/open-sse` **пакет робочої області npm**. Вихідний код імпортує його через `@omniroute/open-sse/...` (вирішено Next.js `transpilePackages`). Шляхи до файлів у цьому документі все ще використовують назву каталогу `open-sse/` для узгодженості. -6. Діаграми на інформаційній панелі використовують **Recharts** (на основі SVG) для доступної інтерактивної візуалізації аналітики (гістограми використання моделі, таблиці розбивки постачальників із показниками успіху). -7. Тести E2E використовують **Playwright** (`tests/e2e/`), запускають через `npm run test:e2e`. У модульних тестах використовується **Node.js Test Runner** (`tests/unit/`), запускається через `npm run test:plan3`. Вихідним кодом під `src/` є **TypeScript** (`.ts`/`.tsx`); робоча область `open-sse/` залишається JavaScript (`.js`). -8. Сторінка налаштувань організована на 5 вкладках: Безпека, Маршрутизація (6 глобальних стратегій: спочатку заповнює, циклічна, p2c, випадкова, найменш використовувана, оптимізована за витратами), Стійкість (редаговані обмеження швидкості, автоматичний вимикач, політики), ШІ (бюджет мислення, системна підказка, кеш підказок), Додатково (проксі). +## Operational Verification Checklist -## Контрольний список операційної перевірки - -- Збірка з джерела: `npm run build` -- Створити образ Docker: `docker build -t omniroute .` -- Запустіть службу та перевірте: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- Цільова базова URL-адреса CLI має бути `http://:20128/v1`, коли `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/uk-UA/CODEBASE_DOCUMENTATION.md b/docs/i18n/uk-UA/CODEBASE_DOCUMENTATION.md index 83e3893b24..303880c198 100644 --- a/docs/i18n/uk-UA/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/uk-UA/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Документація кодової бази +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Вичерпний, зручний для початківців посібник із **omniroute** багатопровайдерного проксі-маршрутизатора AI. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Що таке omniroute? +## 1. What Is omniroute? -omniroute — це **проксі-маршрутизатор**, який знаходиться між клієнтами AI (Claude CLI, Codex, Cursor IDE тощо) та постачальниками AI (Anthropic, Google, OpenAI, AWS, GitHub тощо). Це вирішує одну велику проблему: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Різні клієнти ШІ розмовляють різними «мовами» (форматами API), і різні постачальники ШІ також очікують різних «мов».** omniroute автоматично перекладає між ними. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Думайте про це як про універсального перекладача в Організації Об’єднаних Націй — будь-який делегат може говорити будь-якою мовою, і перекладач перетворює її для будь-якого іншого делегата. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Огляд архітектури +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Основний принцип: комплексний переклад +### Core Principle: Hub-and-Spoke Translation -Усі трансляції форматів проходять через **формат OpenAI як центр**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Це означає, що вам потрібно лише **N перекладачів** (по одному на формат) замість **N²** (кожна пара). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Структура проекту +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Розбивка по модулях +## 4. Module-by-Module Breakdown -### 4.1 Конфігурація (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**Єдине джерело правди** для всіх конфігурацій постачальників. +The **single source of truth** for all provider configuration. -| Файл | Призначення | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | Об’єкт `PROVIDERS` з базовими URL-адресами, обліковими даними OAuth (за замовчуванням), заголовками та системними підказками за замовчуванням для кожного постачальника. Також визначає `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` та `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Завантажує зовнішні облікові дані з `data/provider-credentials.json` та об’єднує їх із жорстко запрограмованими параметрами за замовчуванням у `PROVIDERS`. Зберігає секрети поза контролем джерела, зберігаючи зворотну сумісність. | -| `providerModels.ts` | Центральний реєстр моделей: псевдоніми постачальників карт → ідентифікатори моделей. Такі функції, як `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Системні інструкції, введені в запити Codex (обмеження редагування, правила пісочниці, політики затвердження). | -| `defaultThinkingSignature.ts` | Стандартні «мислячі» підписи для моделей Claude і Gemini. | -| `ollamaModels.ts` | Визначення схеми для локальних моделей Ollama (назва, розмір, сімейство, квантування). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Потік завантаження облікових даних +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Виконавці (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Виконавці інкапсулюють **специфічну логіку постачальника** за допомогою **шаблону стратегії**. Кожен виконавець замінює базові методи за потреби. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Виконавець | Постачальник | Ключові спеціалізації | -| ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Абстрактна база: створення URL-адреси, заголовки, логіка повтору, оновлення облікових даних | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Оновлення універсального маркера OAuth для стандартних постачальників | -| `antigravity.ts` | Google Cloud Code | Генерація ідентифікатора проекту/сеансу, резервна копія кількох URL-адрес, користувацький аналіз повторної спроби з повідомлень про помилку ("скинути через 2 год. 7 хв. 23 с.") | -| `cursor.ts` | Курсор IDE | **Найскладніше**: автентифікація контрольної суми SHA-256, кодування запиту Protobuf, двійковий EventStream → аналіз відповіді SSE | -| `codex.ts` | OpenAI Codex | Впроваджує системні інструкції, керує рівнями мислення, видаляє непідтримувані параметри | -| `gemini-cli.ts` | Google Gemini CLI | Створення спеціальної URL-адреси (`streamGenerateContent`), оновлення маркера Google OAuth | -| `github.ts` | Копілот GitHub | Подвійна система маркерів (GitHub OAuth + маркер Copilot), імітація заголовка VSCode | -| `kiro.ts` | AWS CodeWhisperer | Двійковий аналіз AWS EventStream, кадри подій AMZN, оцінка маркерів | -| `index.ts` | — | Фабрика: відображає ім’я постачальника → клас виконавця, із резервним варіантом за замовчуванням | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 Обробники (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**Рівень оркестровки** — координує переклад, виконання, потокове передавання та обробку помилок. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Файл | Призначення | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Центральний оркестр** (~600 рядків). Обробляє повний життєвий цикл запиту: виявлення формату → переклад → відправка виконавця → потокова/непотокова відповідь → оновлення маркера → обробка помилок → журнал використання. | -| `responsesHandler.ts` | Адаптер для API відповідей OpenAI: перетворює формат відповідей → Завершення чату → надсилає до `chatCore` → перетворює SSE назад у формат відповідей. | -| `embeddings.ts` | Обробник генерації вбудовування: розпізнає модель вбудовування → постачальник, надсилає до API постачальника, повертає відповідь на вбудовування, сумісну з OpenAI. Підтримує 6+ провайдерів. | -| `imageGeneration.ts` | Обробник генерації зображень: розпізнає модель зображення → постачальник, підтримує режими, сумісні з OpenAI, Gemini-image (Antigravity) і резервний (Nebius). Повертає base64 або URL-зображення. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Життєвий цикл запиту (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 Послуги (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Бізнес-логіка, яка підтримує обробники та виконавці. +Business logic that supports the handlers and executors. -| Файл | Призначення | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `provider.ts` | **Виявлення формату** (`detectFormat`): аналізує структуру тіла запиту, щоб визначити формати Claude/OpenAI/Gemini/Antigravity/Responses (включає `max_tokens` евристику для Claude). Також: створення URL-адрес, створення заголовків, нормалізація конфігурації мислення. Підтримує динамічних постачальників `openai-compatible-*` та `anthropic-compatible-*`. | -| `model.ts` | Синтаксичний аналіз рядка моделі (`claude/model-name` → `{provider: "claude", model: "model-name"}`), вирішення псевдонімів із виявленням зіткнень, очищення вхідних даних (відхиляє обхід шляхів/контрольні символи) та вирішення інформації про модель із підтримкою асинхронного засобу отримання псевдонімів. | -| `accountFallback.ts` | Обробка ліміту швидкості: експоненціальна віддача (1 с → 2 с → 4 с → макс. 2 хв), керування відновленням облікового запису, класифікація помилок (які помилки викликають відкат, а які ні). | -| `tokenRefresh.ts` | Оновлення маркерів OAuth для **кожного постачальника**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Включає в себе кеш дедуплікації обіцянок у польоті та повторну спробу з експоненціальним відстрочкою. | -| `combo.ts` | **Комбіновані моделі**: ланцюжки резервних моделей. Якщо модель A виходить з ладу через помилку, придатну для повернення, спробуйте модель B, потім C тощо. Повертає фактичні коди стану висхідного каналу. | -| `usage.ts` | Отримує дані про квоту/використання з API постачальника (квоти GitHub Copilot, квоти моделі Antigravity, обмеження швидкості Codex, аналіз використання Kiro, налаштування Claude). | -| `accountSelector.ts` | Інтелектуальний вибір облікового запису з алгоритмом підрахунку балів: враховує пріоритет, стан здоров’я, позицію циклічного циклу та стан відновлення, щоб вибрати оптимальний обліковий запис для кожного запиту. | -| `contextManager.ts` | Керування життєвим циклом контексту запиту: створює та відстежує об’єкти контексту кожного запиту з метаданими (ідентифікатор запиту, часові позначки, інформація про постачальника) для налагодження та журналювання. | -| `ipFilter.ts` | Контроль доступу на основі IP: підтримує режими білого та чорного списків. Перевіряє IP клієнта на відповідність налаштованим правилам перед обробкою запитів API. | -| `sessionManager.ts` | Відстеження сеансу за допомогою відбитків пальців клієнта: відстежує активні сеанси за допомогою хешованих ідентифікаторів клієнта, відстежує кількість запитів і надає показники сеансу. | -| `signatureCache.ts` | Кеш дедуплікації на основі підписів запитів: запобігає повторюваним запитам, кешуючи останні підписи запитів і повертаючи кешовані відповіді для ідентичних запитів протягом певного періоду часу. | -| `systemPrompt.ts` | Впровадження глобальної системної підказки: додає або додає настроювану системну підказку до всіх запитів із обробкою сумісності для кожного постачальника. | -| `thinkingBudget.ts` | Управління бюджетом резонансних токенів: підтримує прохідний, автоматичний (конфігурація розгалуженого мислення), спеціальний (фіксований бюджет) і адаптивний (з урахуванням складності) режими для керування жетонами мислення/міркування. | -| `wildcardRouter.ts` | Маршрутизація шаблонів шаблонів підстановки: розв’язує шаблони підстановки (наприклад, `*/claude-*`) до конкретних пар постачальник/модель на основі доступності та пріоритету. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Дедуплікація оновлення маркера +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Запасний автомат стану облікового запису +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Комбінована модель ланцюжка +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 Перекладач (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**Система перекладу форматів**, яка використовує систему плагінів із самореєстрацією. +The **format translation engine** using a self-registering plugin system. -#### Архітектура +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Довідник | Файли | Опис | -| ------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 перекладачів | Перетворюйте тіла запиту між форматами. Кожен файл самостійно реєструється через `register(from, to, fn)` під час імпорту. | -| `response/` | 7 перекладачів | Перетворюйте фрагменти потокової відповіді між форматами. Обробляє типи подій SSE, блоки мислення, виклики інструментів. | -| `helpers/` | 6 помічників | Спільні утиліти: `claudeHelper` (вилучення системних підказок, конфігурація мислення), `geminiHelper` (відображення частин/вмісту), `openaiHelper` (фільтрування формату), `toolCallHelper` (генерація ідентифікатора, впровадження відсутніх відповідей), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Система перекладу: `translateRequest()`, `translateResponse()`, державне управління, реєстр. | -| `formats.ts` | — | Константи формату: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Дизайн ключа: плагіни, що самостійно реєструються +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,17 +395,17 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Утиліти (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Файл | Призначення | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `error.ts` | Формування відповіді на помилку (формат, сумісний з OpenAI), синтаксичний аналіз помилок вгорі, вилучення часу повторної спроби Antigravity з повідомлень про помилки, потокова передача помилок SSE. | -| `stream.ts` | **SSE Transform Stream** — основний потоковий конвеєр. Два режими: `TRANSLATE` (повноформатний переклад) і `PASSTHROUGH` (нормалізувати + витягнути використання). Керується буферизацією фрагментів, оцінкою використання, відстеженням довжини вмісту. Екземпляри потокового кодера/декодера уникають спільного стану. | -| `streamHelpers.ts` | Утиліти SSE низького рівня: `parseSSELine` (толерантний до пробілів), `hasValuableContent` (фільтрує порожні фрагменти для OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (серіалізація SSE з урахуванням формату за допомогою `perf_metrics` очищення). | -| `usageTracking.ts` | Видалення використання маркерів із будь-якого формату (Claude/OpenAI/Gemini/Responses), оцінка з окремими співвідношеннями символів на маркер для інструментів/повідомлень, додавання буфера (2000 запасів маркерів), фільтрація полів для певного формату, консольне журналювання з кольорами ANSI. | -| `requestLogger.ts` | Реєстрація запитів на основі файлів (увімкніться через `ENABLE_REQUEST_LOGS=true`). Створює папки сеансу з пронумерованими файлами: `1_req_client.json` → `7_res_client.txt`. Весь ввід-вивід є асинхронним (запустив і забув). Маскує чутливі заголовки. | -| `bypassHandler.ts` | Перехоплює певні шаблони від Claude CLI (вилучення заголовків, розминка, підрахунок) і повертає фальшиві відповіді без виклику жодного постачальника. Підтримує як потокове, так і не потокове. Навмисно обмежено областю CLI Claude. | -| `networkProxy.ts` | Вирішує URL-адресу вихідного проксі-сервера для даного постачальника з пріоритетом: конфігурація для конкретного постачальника → глобальна конфігурація → змінні середовища (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Підтримує виключення `NO_PROXY`. Кеш конфігурації на 30 с. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | #### SSE Streaming Pipeline @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Структура сеансу реєстратора запитів +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Рівень програми (`src/`) +### 4.7 Application Layer (`src/`) -| Довідник | Призначення | -| ------------- | -------------------------------------------------------------------------------------------------------------------- | -| `src/app/` | Веб-інтерфейс користувача, маршрути API, проміжне програмне забезпечення Express, обробники зворотного виклику OAuth | -| `src/lib/` | Доступ до бази даних (`localDb.ts`, `usageDb.ts`), автентифікація, спільний | -| `src/mitm/` | Проксі-утиліти Man-in-the-middle для перехоплення трафіку провайдера | -| `src/models/` | Визначення моделі бази даних | -| `src/shared/` | Обгортки навколо функцій open-sse (провайдер, потік, помилка тощо) | -| `src/sse/` | Обробники кінцевих точок SSE, які підключають бібліотеку open-sse до експрес-маршрутів | -| `src/store/` | Застосування управління станом | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Відомі маршрути API +#### Notable API Routes -| Маршрут | Методи | Призначення | -| --------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | GET/POST/DELETE | CRUD для спеціальних моделей на постачальника | -| `/api/models/catalog` | ОТРИМАТИ | Зведений каталог усіх моделей (чат, вбудовування, зображення, настроювання), згрупований за постачальником | -| `/api/settings/proxy` | GET/PUT/DELETE | Конфігурація ієрархічного вихідного проксі (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | Опублікувати | Перевіряє підключення проксі та повертає загальнодоступну IP-адресу/затримку | -| `/v1/providers/[provider]/chat/completions` | Опублікувати | Спеціальне завершення чату для кожного постачальника з перевіркою моделі | -| `/v1/providers/[provider]/embeddings` | Опублікувати | Спеціальне вбудовування для кожного постачальника з перевіркою моделі | -| `/v1/providers/[provider]/images/generations` | Опублікувати | Спеціальне створення зображень для кожного постачальника з перевіркою моделі | -| `/api/settings/ip-filter` | GET/PUT | Керування списком дозволених/чорних IP-адрес | -| `/api/settings/thinking-budget` | GET/PUT | Конфігурація бюджету токена міркування (прохідний/автоматичний/спеціальний/адаптивний) | -| `/api/settings/system-prompt` | GET/PUT | Глобальна системна підказка для всіх запитів | -| `/api/sessions` | ОТРИМАТИ | Відстеження активної сесії та метрики | -| `/api/rate-limits` | ОТРИМАТИ | Статус обмеження ставки на обліковий запис | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Ключові шаблони проектування +## 5. Key Design Patterns -### 5.1 Переклад Hub-and-Spoke +### 5.1 Hub-and-Spoke Translation -Усі формати перекладаються через **формат OpenAI як центр**. Додавання нового постачальника вимагає лише написання **однієї пари** перекладачів (до/з OpenAI), а не N пар. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Шаблон стратегії виконавця +### 5.2 Executor Strategy Pattern -Кожен провайдер має спеціальний клас виконавця, успадкований від `BaseExecutor`. Фабрика в `executors/index.ts` вибирає правильний під час виконання. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Система плагінів із самореєстрацією +### 5.3 Self-Registering Plugin System -Модулі перекладача реєструються під час імпорту через `register()`. Додавання нового перекладача означає лише створення файлу та його імпорт. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Резервний обліковий запис із експоненціальним відстрочкою +### 5.4 Account Fallback with Exponential Backoff -Коли постачальник повертає 429/401/500, система може перейти до наступного облікового запису, застосовуючи експоненціальне відновлення (1 с → 2 с → 4 с → макс. 2 хв). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### Ланцюги комбінованих моделей 5.5 +### 5.5 Combo Model Chains -"Combo" групує кілька рядків `provider/model`. Якщо перший не вдається, автоматично поверніться до наступного. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Потоковий переклад із збереженням стану +### 5.6 Stateful Streaming Translation -Трансляція відповіді підтримує стан у блоках SSE (відстеження блоків мислення, накопичення викликів інструментів, індексація блоків вмісту) через механізм `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Буфер безпеки використання +### 5.7 Usage Safety Buffer -Буфер на 2000 маркерів додається до звітів про використання, щоб запобігти перевищенню клієнтами обмежень вікон контексту через накладні витрати на системні підказки та переклад формату. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Підтримувані формати +## 6. Supported Formats -| Формат | Напрям | Ідентифікатор | -| ---------------------- | -------------- | ------------------ | -| Завершення чату OpenAI | джерело + ціль | `openai` | -| OpenAI Responses API | джерело + ціль | `openai-responses` | -| Антропний Клод | джерело + ціль | `claude` | -| Google Gemini | джерело + ціль | `gemini` | -| Google Gemini CLI | тільки мета | `gemini-cli` | -| Антигравітація | джерело + ціль | `antigravity` | -| AWS Kiro | тільки мета | `kiro` | -| Курсор | тільки мета | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Підтримувані постачальники +## 7. Supported Providers -| Постачальник | Метод авторизації | Виконавець | Ключові примітки | -| ------------------------ | ------------------------------- | ---------------- | ------------------------------------------------------------------------- | -| Антропний Клод | Ключ API або OAuth | За замовчуванням | Використовує заголовок `x-api-key` | -| Google Gemini | Ключ API або OAuth | За замовчуванням | Використовує заголовок `x-goog-api-key` | -| Google Gemini CLI | OAuth | GeminiCLI | Використовує кінцеву точку `streamGenerateContent` | -| Антигравітація | OAuth | Антигравітація | Резервний варіант із кількома URL-адресами, настроюваний повторний аналіз | -| OpenAI | Ключ API | За замовчуванням | Автентифікація стандартного носія | -| Кодекс | OAuth | Кодекс | Впроваджує системні інструкції, керує мисленням | -| Копілот GitHub | OAuth + маркер Copilot | Github | Подвійний маркер, імітація заголовка VSCode | -| Кіро (AWS) | AWS SSO OIDC або Social | Кіро | Розбір двійкового потоку подій | -| Курсор IDE | Аутентифікація контрольної суми | Курсор | Кодування Protobuf, контрольні суми SHA-256 | -| Квен | OAuth | За замовчуванням | Стандартна авторизація | -| iFlow | OAuth (базовий + носій) | За замовчуванням | Заголовок подвійної авторизації | -| OpenRouter | Ключ API | За замовчуванням | Автентифікація стандартного носія | -| GLM, Kimi, MiniMax | Ключ API | За замовчуванням | Claude-сумісний, використовуйте `x-api-key` | -| `openai-compatible-*` | Ключ API | За замовчуванням | Динамічний: будь-яка кінцева точка, сумісна з OpenAI | -| `anthropic-compatible-*` | Ключ API | За замовчуванням | Динамічний: будь-яка Claude-сумісна кінцева точка | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Підсумок потоку даних +## 8. Data Flow Summary -### Запит на потокове передавання +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Непотоковий запит +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Обхідний потік (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/uk-UA/FEATURES.md b/docs/i18n/uk-UA/FEATURES.md index cb6aaff545..82cc73b67b 100644 --- a/docs/i18n/uk-UA/FEATURES.md +++ b/docs/i18n/uk-UA/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Галерея функцій приладової панелі +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Візуальний путівник по кожному розділу інформаційної панелі OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Постачальники +## 🔌 Providers -Керуйте підключеннями постачальників AI: постачальників OAuth (Claude Code, Codex, Gemini CLI), постачальників ключів API (Groq, DeepSeek, OpenRouter) і безкоштовних постачальників (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Комбо +## 🎨 Combos -Створюйте комбіновані моделі маршрутизації за допомогою 6 стратегій: спочатку заповнюйте, циклічний, вибір двох варіантів, випадковий, найменш використовуваний і оптимізований за витратами. Кожен комбо об’єднує кілька моделей із автоматичним резервним копіюванням. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Аналітика +## 📊 Analytics -Комплексна аналітика використання із споживанням токенів, оцінками витрат, тепловими картами активності, тижневими діаграмами розподілу та розподілом за постачальниками. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Здоров'я системи +## 🏥 System Health -Моніторинг у режимі реального часу: безвідмовна робота, пам’ять, версія, процентилі затримки (p50/p95/p99), статистика кешу та стани автоматичного вимикача постачальника. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Ігровий майданчик для перекладачів +## 🔧 Translator Playground -Чотири режими для налагодження перекладів API: **Playground** (конвертер форматів), **Chat Tester** (живі запити), **Test Bench** (пакетні тести) і **Live Monitor** (потік у реальному часі). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Налаштування +## 🎮 Model Playground _(v2.0.9+)_ -Загальні параметри, системне сховище, керування резервним копіюванням (база даних експорту/імпорту), зовнішній вигляд (темний/світлий режим), безпека (включає захист кінцевих точок API і блокування спеціального постачальника), маршрутизація, стійкість і розширена конфігурація. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Інструменти CLI +## 🔧 CLI Tools -Конфігурація в один клік для інструментів кодування AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code та Antigravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Журнали запитів +## 🤖 CLI Agents _(v2.0.11+)_ -Реєстрація запитів у режимі реального часу з фільтрацією за постачальником, моделлю, обліковим записом і ключем API. Показує коди стану, використання маркера, затримку та деталі відповіді. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Кінцева точка API +## 🌐 API Endpoint -Ваша уніфікована кінцева точка API з розподілом можливостей: завершення чату, вбудовування, генерація зображень, зміна рейтингу, транскрипція аудіо та зареєстровані ключі API. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/uk-UA/TROUBLESHOOTING.md b/docs/i18n/uk-UA/TROUBLESHOOTING.md index 645cc8b406..120092d63c 100644 --- a/docs/i18n/uk-UA/TROUBLESHOOTING.md +++ b/docs/i18n/uk-UA/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Усунення несправностей +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Поширені проблеми та рішення для OmniRoute. +Common problems and solutions for OmniRoute. --- -## Швидкі виправлення +## Quick Fixes -| Проблема | Рішення | -| -------------------------------------------------------- | ------------------------------------------------------------------------------ | -| Перший вхід не працює | Перевірте `INITIAL_PASSWORD` в `.env` (за замовчуванням: `123456`) | -| Інформаційна панель відкривається на неправильному порту | Установити `PORT=20128` та `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Немає журналів запитів під `logs/` | Установити `ENABLE_REQUEST_LOGS=true` | -| EACCES: у дозволі відмовлено | Установіть `DATA_DIR=/path/to/writable/dir` на заміну `~/.omniroute` | -| Стратегія маршрутизації не зберігається | Оновлення до версії 1.4.11+ (виправлення схеми Zod для збереження налаштувань) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Проблеми постачальника +## Provider Issues -### "Мовна модель не надавала повідомлень" +### "Language model did not provide messages" -**Причина:** Квота постачальника вичерпана. +**Cause:** Provider quota exhausted. -**Виправлення:** +**Fix:** -1. Перевірте трекер квот на інформаційній панелі -2. Використовуйте комбінацію з запасними рівнями -3. Перейдіть на дешевший/безкоштовний рівень +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Обмеження швидкості +### Rate Limiting -**Причина:** Квота підписки вичерпана. +**Cause:** Subscription quota exhausted. -**Виправлення:** +**Fix:** -- Додати запасний варіант: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Використовуйте GLM/MiniMax як дешеву резервну копію +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Маркер OAuth минув +### OAuth Token Expired -OmniRoute автоматично оновлює маркери. Якщо проблеми не зникають: +OmniRoute auto-refreshes tokens. If issues persist: -1. Інформаційна панель → Постачальник → Повторне підключення -2. Видаліть і знову додайте підключення провайдера +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Проблеми з хмарою +## Cloud Issues -### Помилки хмарної синхронізації +### Cloud Sync Errors -1. Перевірте, чи `BASE_URL` вказує на ваш запущений екземпляр (наприклад, `http://localhost:20128`) -2. Перевірте, чи `CLOUD_URL` вказує на кінцеву точку вашої хмари (наприклад, `https://omniroute.dev`) -3. Зберігайте значення `NEXT_PUBLIC_*` у відповідності зі значеннями на стороні сервера +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Cloud `stream=false` Повертає 500 +### Cloud `stream=false` Returns 500 -**Симптом:** `Unexpected token 'd'...` на хмарній кінцевій точці для непотокових викликів. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Причина:** Upstream повертає корисне навантаження SSE, тоді як клієнт очікує JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Рішення:** використовуйте `stream=true` для прямих дзвінків із хмари. Місцеве середовище виконання включає SSE→JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Хмара повідомляє, що підключено, але "недійсний ключ API" +### Cloud Says Connected but "Invalid API key" -1. Створіть новий ключ із локальної інформаційної панелі (`/api/keys`) -2. Запустіть хмарну синхронізацію: увімкніть Cloud → Синхронізувати зараз -3. Старі/несинхронізовані ключі все ще можуть повертати `401` у хмарі +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Проблеми Docker +## Docker Issues -### Інструмент CLI показує, що не встановлено +### CLI Tool Shows Not Installed -1. Перевірте поля часу виконання: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Для портативного режиму: використовуйте цільове зображення `runner-cli` (пакет CLI) -3. Для режиму монтування хосту: встановіть `CLI_EXTRA_PATHS` і змонтуйте каталог bin хоста як доступний лише для читання -4. Якщо `installed=true` та `runnable=false`: двійковий файл знайдено, але перевірка працездатності не пройшла +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Швидка перевірка часу виконання +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Проблеми з вартістю +## Cost Issues -### Високі витрати +### High Costs -1. Перевірте статистику використання в Інформаційна панель → Використання -2. Переключіть основну модель на GLM/MiniMax -3. Використовуйте безкоштовний рівень (Gemini CLI, iFlow) для некритичних завдань -4. Встановіть бюджет витрат на ключ API: Інформаційна панель → Ключі API → Бюджет +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Налагодження +## Debugging -### Увімкнути журнали запитів +### Enable Request Logs -Установіть `ENABLE_REQUEST_LOGS=true` у вашому файлі `.env`. Журнали відображаються в каталозі `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Перевірити працездатність постачальника +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Сховище часу виконання +### Runtime Storage -- Основний стан: `${DATA_DIR}/db.json` (постачальники, комбо, псевдоніми, ключі, налаштування) -- Використання: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Журнали запитів: `/logs/...` (коли `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Проблеми з автоматичним вимикачем +## Circuit Breaker Issues -### Постачальник застряг у стані ВІДКРИТО +### Provider stuck in OPEN state -Коли автоматичний вимикач постачальника ВІДКРИТО, запити блокуються до закінчення часу відновлення. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Виправлення:** +**Fix:** -1. Перейдіть до **Інформаційна панель → Налаштування → Стійкість** -2. Перевірте плату автоматичного вимикача для постраждалого постачальника -3. Натисніть **Скинути все**, щоб очистити всі вимикачі, або зачекайте, доки закінчиться час відновлення -4. Перед скиданням переконайтеся, що постачальник дійсно доступний +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Постачальник продовжує вмикати автоматичний вимикач +### Provider keeps tripping the circuit breaker -Якщо постачальник постійно переходить у стан ВІДКРИТО: +If a provider repeatedly enters OPEN state: -1. Перевірте **Інформаційна панель → Справність → Справність постачальника**, щоб дізнатися про збій -2. Перейдіть до **Налаштування → Стійкість → Профілі постачальників** і збільште поріг відмов -3. Перевірте, чи постачальник змінив обмеження API або вимагає повторної автентифікації -4. Перегляньте телеметрію затримки — висока затримка може спричинити збої, пов’язані з тайм-аутом +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Проблеми з транскрипцією аудіо +## Audio Transcription Issues -### Помилка "Непідтримувана модель". +### "Unsupported model" error -- Переконайтеся, що ви використовуєте правильний префікс: `deepgram/nova-3` або `assemblyai/best` -- Переконайтеся, що постачальник підключено в **Інформаційна панель → Постачальники** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Транскрипція повертається порожньою або не вдається +### Transcription returns empty or fails -- Перевірте підтримувані аудіоформати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Переконайтеся, що розмір файлу відповідає обмеженням постачальника (зазвичай < 25 МБ) -- Перевірте дійсність ключа API провайдера в картці провайдера +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Налагодження перекладача +## Translator Debugging -Використовуйте **Інформаційну панель → Перекладач**, щоб усунути проблеми з перекладом формату: +Use **Dashboard → Translator** to debug format translation issues: -| Режим | Коли використовувати | -| ------------------------ | -------------------------------------------------------------------------------------------------------------- | -| **Дитячий майданчик** | Порівняйте формати введення/виведення поруч — вставте невдалий запит, щоб побачити, як він перекладається | -| **Тестувальник чату** | Надсилайте живі повідомлення та перевіряйте повне корисне навантаження запитів/відповідей, включаючи заголовки | -| **Випробувальний стенд** | Запустіть пакетне тестування комбінацій форматів, щоб знайти, які переклади порушені | -| **Живий монітор** | Слідкуйте за потоком запитів у реальному часі, щоб виявити періодичні проблеми з перекладом | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Поширені проблеми формату +### Common format issues -- **Теги мислення не відображаються** — перевірте, чи підтримує цільовий постачальник мислення та налаштування бюджету мислення -- **Відмова від викликів інструментів** — деякі переклади форматів можуть видаляти непідтримувані поля; перевірити в режимі Playground -- **Відсутня системна підказка** — Клод і Близнюки по-різному обробляють системні підказки; перевірити результат перекладу -- **SDK повертає необроблений рядок замість об’єкта** — Виправлено у версії 1.1.0: дезінфікуючий засіб відповіді тепер видаляє нестандартні поля (`x_groq`, `usage_breakdown` тощо), які викликають помилки підтвердження OpenAI SDK Pydantic -- **GLM/ERNIE відхиляє роль `system`** — Виправлено у версії 1.1.0: нормалізатор ролі автоматично об’єднує системні повідомлення в повідомлення користувача для несумісних моделей -- **`developer` роль не розпізнається** — Виправлено у версії 1.1.0: автоматично конвертовано в `system` для постачальників, які не є OpenAI -- **`json_schema` не працює з Gemini** — Виправлено у версії 1.1.0: `response_format` тепер перетворено на `responseMimeType` + `responseSchema` Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Налаштування стійкості +## Resilience Settings -### Автоматичне обмеження швидкості не спрацьовує +### Auto rate-limit not triggering -- Автоматичне обмеження швидкості стосується лише постачальників ключів API (не OAuth/підписки) -- Переконайтеся, що **Налаштування → Стійкість → Профілі постачальників** увімкнено автоматичне обмеження швидкості -- Перевірте, чи повертає постачальник коди статусу `429` або заголовки `Retry-After` +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Налаштування експоненціального відступу +### Tuning exponential backoff -Профілі постачальників підтримують такі налаштування: +Provider profiles support these settings: -- **Базова затримка** — початковий час очікування після першої помилки (за замовчуванням: 1 с) -- **Макс. затримка** — обмеження максимального часу очікування (за замовчуванням: 30 с) -- **Множник** — скільки збільшити затримку на послідовну помилку (за замовчуванням: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Протигромове стадо +### Anti-thundering herd -Коли багато одночасних запитів надходять до постачальника з обмеженою швидкістю, OmniRoute використовує м’ютекс + автоматичне обмеження швидкості для серіалізації запитів і запобігання каскадним помилкам. Це відбувається автоматично для постачальників ключів API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Все ще застрягли? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Проблеми GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Архітектура**: див. [link](ARCHITECTURE.md) для внутрішніх деталей -- **API Reference**: див. [link](API_REFERENCE.md) для всіх кінцевих точок -- **Інформаційна панель справності**: перевірте **Інформаційна панель → Здоров’я**, щоб дізнатися про стан системи в реальному часі -- **Перекладач**: використовуйте **Інформаційна панель → Перекладач** для усунення проблем із форматом +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/uk-UA/USER_GUIDE.md b/docs/i18n/uk-UA/USER_GUIDE.md index e48a59c19f..5a043224df 100644 --- a/docs/i18n/uk-UA/USER_GUIDE.md +++ b/docs/i18n/uk-UA/USER_GUIDE.md @@ -1,12 +1,12 @@ -# Керівництво користувача +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Повний посібник із налаштування постачальників, створення комбінацій, інтеграції інструментів CLI та розгортання OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Зміст +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 Короткий огляд цін +## 💰 Pricing at a Glance -| Рівень | Постачальник | Вартість | Скидання квоти | Найкраще для | -| ------------------ | ---------------- | ------------------------ | ----------------------------- | --------------------------- | -| **💳 ПІДПИСКА** | Клод Код (Pro) | 20 доларів США на місяць | 5 годин + щотижня | Вже підписані | -| | Codex (Plus/Pro) | $20-200/міс | 5 годин + щотижня | Користувачі OpenAI | -| | Gemini CLI | **БЕЗКОШТОВНО** | 180 тис./місяць + 1 тис./день | всі! | -| | Копілот GitHub | $10-19/міс | Щомісяця | Користувачі GitHub | -| **🔑 КЛЮЧ API** | DeepSeek | Оплата за використання | Жодного | Дешеві міркування | -| | Groq | Оплата за використання | Жодного | Надшвидкий висновок | -| | xAI (Грок) | Оплата за використання | Жодного | Грок 4 міркування | -| | Містраль | Оплата за використання | Жодного | Моделі, розміщені в ЄС | -| | Розгубленість | Оплата за використання | Жодного | Search-augmented | -| | Разом AI | Оплата за використання | Жодного | Моделі з відкритим кодом | -| | Феєрверк AI | Оплата за використання | Жодного | Швидкі зображення FLUX | -| | Головний мозок | Оплата за використання | Жодного | Швидкість вафельної шкали | -| | Cohere | Оплата за використання | Жодного | Команда R+ RAG | -| | NVIDIA NIM | Оплата за використання | Жодного | Моделі підприємства | -| **💰 ДЕШЕВО** | GLM-4.7 | $0,6/1 млн | Щодня о 10 ранку | Резервне копіювання бюджету | -| | MiniMax M2.1 | $0,2/1 млн | 5-годинний роликовий | Найдешевший варіант | -| | Кімі К2 | 9 $/міс квартира | 10 млн токенів/міс | Передбачувана вартість | -| **🆓 БЕЗКОШТОВНО** | iFlow | $0 | Необмежений | 8 моделей безкоштовно | -| | Квен | $0 | Необмежений | 3 моделі безкоштовно | -| | Кіро | $0 | Необмежений | Клод безкоштовно | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Порада професіонала:** Почніть із Gemini CLI (180 тис. безкоштовно/місяць) + iFlow (необмежено безкоштовно) = 0 доларів США! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Випадки використання +## 🎯 Use Cases -### Випадок 1: «У мене є підписка на Claude Pro» +### Case 1: "I have Claude Pro subscription" -**Проблема:** Квота закінчується невикористаною, обмеження швидкості під час інтенсивного кодування +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Випадок 2: "Я хочу нульову вартість" +### Case 2: "I want zero cost" -**Проблема:** не можу дозволити собі підписку, потрібне надійне кодування ШІ +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Випадок 3: «Мені потрібне кодування 24/7, без перерв» +### Case 3: "I need 24/7 coding, no interruptions" -**Проблема:** Дедлайни, не можу дозволити собі простою +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Випадок 4: «Я хочу БЕЗКОШТОВНОГО ШІ в OpenClaw» +### Case 4: "I want FREE AI in OpenClaw" -**Проблема:** потрібен помічник штучного інтелекту в програмах для обміну повідомленнями, повністю безкоштовний +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,9 +109,9 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Налаштування постачальника +## 📖 Provider Setup -### 🔐 Постачальники підписки +### 🔐 Subscription Providers #### Claude Code (Pro/Max) @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Професійна порада:** використовуйте Opus для складних завдань, Sonnet для швидкості. OmniRoute відстежує квоту на модель! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (БЕЗКОШТОВНО 180K/місяць!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**Найкраще:** Величезний безкоштовний рівень! Використовуйте це перед платними рівнями. +**Best Value:** Huge free tier! Use this before paid tiers. -#### Копілот GitHub +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Дешеві постачальники +### 💰 Cheap Providers -#### GLM-4.7 (щоденне скидання, $0,6/1 млн) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Зареєструйтеся: [Zhipu AI](https://open.bigmodel.cn/) -2. Отримайте ключ API від Coding Plan -3. Інформаційна панель → Додати ключ API: Постачальник: `glm`, ключ API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Використання:** `glm/glm-4.7` — **Порада професіонала:** План кодування пропонує 3× квоту за 1/7 вартості! Скидання щодня о 10:00. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (5 годин скидання, $0,20/1 млн) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Зареєструйтеся: [MiniMax](https://www.minimax.io/) -2. Отримати ключ API → Інформаційна панель → Додати ключ API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Використовуйте:** `minimax/MiniMax-M2.1` — **Порада:** Найдешевший варіант для довгого контексту (1 млн токенів)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/місяць) +#### Kimi K2 ($9/month flat) -1. Підпишіться: [Moonshot AI](https://platform.moonshot.ai/) -2. Отримати ключ API → Інформаційна панель → Додати ключ API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Використання:** `kimi/kimi-latest` — **Порада професіонала:** Фіксовані 9 доларів США на місяць за 10 мільйонів токенів = 0,90 доларів США за 1 млн. ефективних витрат! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 БЕЗКОШТОВНІ постачальники +### 🆓 FREE Providers -#### iFlow (8 БЕЗКОШТОВНИХ моделей) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 БЕЗКОШТОВНІ моделі) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Кіро (Клод БЕЗКОШТОВНО) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Комбо +## 🎨 Combos -### Приклад 1: максимізація підписки → дешеве резервне копіювання +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Приклад 2: лише безкоштовно (нульова вартість) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 Інтеграція CLI +## 🔧 CLI Integration -### Курсор IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Клод Код +### Claude Code -Редагувати `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Редагувати `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ codex "your prompt" } ``` -**Або скористайтеся інформаційною панеллю:** Інструменти CLI → OpenClaw → Auto-config +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Продовжити / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Розгортання +## 🚀 Deployment -### Розгортання VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### Докер +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Для інтегрованого режиму з двійковими файлами CLI дивіться розділ Docker в основних документах. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Змінні середовища +### Environment Variables -| Змінна | За замовчуванням | Опис | -| --------------------- | ------------------------------------ | -------------------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Секрет підпису JWT (**зміни у виробництві**) | -| `INITIAL_PASSWORD` | `123456` | Перший пароль для входу | -| `DATA_DIR` | `~/.omniroute` | Каталог даних (база даних, використання, журнали) | -| `PORT` | рамка за замовчуванням | Сервісний порт (`20128` у прикладах) | -| `HOSTNAME` | рамка за замовчуванням | Прив’язати хост (Docker за замовчуванням `0.0.0.0`) | -| `NODE_ENV` | виконання за замовчуванням | Установіть `production` для розгортання | -| `BASE_URL` | `http://localhost:20128` | Внутрішня базова URL-адреса на стороні сервера | -| `CLOUD_URL` | `https://omniroute.dev` | Базова URL-адреса кінцевої точки хмарної синхронізації | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Секрет HMAC для згенерованих ключів API | -| `REQUIRE_API_KEY` | `false` | Примусово застосувати ключ API носія на `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Вмикає журнали запитів/відповідей | -| `AUTH_COOKIE_SECURE` | `false` | Примусово `Secure` cookie автентифікації (за зворотним проксі HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Повну довідку про змінні середовища див. у [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Доступні моделі +## 📊 Available Models
-Переглянути всі доступні моделі +View all available models **Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — БЕЗКОШТОВНО: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**Копілот GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — $0,6/1 млн.: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — $0,2/1 млн.: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — БЕЗКОШТОВНО: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — БЕЗКОШТОВНО: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — БЕЗКОШТОВНО: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -399,11 +458,11 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat **xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**Містраль (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Нерозуміння (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Разом AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` **Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` @@ -417,11 +476,11 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat --- -## 🧩 Розширені функції +## 🧩 Advanced Features -### Спеціальні моделі +### Custom Models -Додайте будь-який ідентифікатор моделі до будь-якого постачальника, не чекаючи оновлення програми: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Або скористайтеся інформаційною панеллю: **Постачальники → [Постачальник] → Спеціальні моделі**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Виділені маршрути постачальників +### Dedicated Provider Routes -Направляйте запити безпосередньо до конкретного постачальника з перевіркою моделі: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Префікс провайдера додається автоматично, якщо його немає. Невідповідні моделі повертають `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Конфігурація мережевого проксі +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Пріоритет:** Специфічний ключ → Специфічний комбінований → Специфічний постачальник → Глобальний → Середовище. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API каталогу моделей +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Повертає моделі, згруповані за постачальниками з типами (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Хмарна синхронізація +### Cloud Sync -- Синхронізація постачальників, комбінацій і налаштувань на всіх пристроях -- Автоматична фонова синхронізація з тайм-аутом + швидка відмова -- Віддавайте перевагу серверним `BASE_URL`/`CLOUD_URL` у виробництві +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production ### LLM Gateway Intelligence (Phase 9) -- **Семантичний кеш** — автоматично кешує непотокові відповіді, температура=0 (обхід за допомогою `X-OmniRoute-No-Cache: true`) -- **Request Idempotency** — Дедуплікує запити протягом 5 секунд через заголовок `Idempotency-Key` або `X-Request-Id` -- **Відстеження прогресу** — підключення до SSE `event: progress` через заголовок `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Ігровий майданчик для перекладачів +### Translator Playground -Доступ через **Інформаційна панель → Перекладач**. Налагодьте та візуалізуйте, як OmniRoute перекладає запити API між постачальниками. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Режим | Призначення | -| ------------------------ | ---------------------------------------------------------------------------------------------- | -| **Дитячий майданчик** | Виберіть вихідний/цільовий формати, вставте запит і миттєво перегляньте перекладений результат | -| **Тестувальник чату** | Надсилайте повідомлення чату через проксі та перевіряйте повний цикл запитів/відповідей | -| **Випробувальний стенд** | Виконайте пакетні тести для кількох комбінацій форматів, щоб перевірити правильність перекладу | -| **Живий монітор** | Переглядайте переклади в реальному часі, коли запити проходять через проксі | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Приклади використання:** +**Use cases:** -- Налагодження причин невдачі певної комбінації клієнт/постачальник -- Переконайтеся, що теги мислення, виклики інструментів і системні підказки перекладаються правильно -- Порівняйте відмінності форматів між форматами OpenAI, Claude, Gemini та Responses API +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Стратегії маршрутизації +### Routing Strategies -Налаштувати через **Інформаційна панель → Налаштування → Маршрутизація**. +Configure via **Dashboard → Settings → Routing**. -| Стратегія | Опис | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -| **Спочатку заповніть** | Використовує облікові записи в пріоритетному порядку — основний обліковий запис обробляє всі запити, поки не стане доступним | -| **Кругова система** | Переглядає всі облікові записи з настроюваним лімітом (за замовчуванням: 3 виклики на обліковий запис) | -| **P2C (Power of Two Choices)** | Вибирає 2 випадкові облікові записи та направляє до більш здорового — балансує навантаження з усвідомленням здоров’я | -| **Випадкове** | Випадково вибирає обліковий запис для кожного запиту за допомогою перемішування Фішера-Єйтса | -| **Найменш використовуваний** | Маршрути до облікового запису з найстарішою міткою часу `lastUsedAt`, рівномірно розподіляючи трафік | -| **Оптимізація вартості** | Маршрути до облікового запису з найнижчим значенням пріоритету, оптимізуючи для найнижчих постачальників | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Псевдоніми моделі підстановки +#### Wildcard Model Aliases -Створіть шаблони символів підстановки, щоб змінити назви моделей: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Символи підстановки підтримують `*` (будь-які символи) і `?` (один символ). +Wildcards support `*` (any characters) and `?` (single character). -#### Резервні ланцюги +#### Fallback Chains -Визначте глобальні резервні ланцюжки, які застосовуються до всіх запитів: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Стійкість і автоматичні вимикачі +### Resilience & Circuit Breakers -Налаштуйте за допомогою **Інформаційна панель → Налаштування → Стійкість**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute реалізує стійкість на рівні постачальника за допомогою чотирьох компонентів: +OmniRoute implements provider-level resilience with four components: -1. **Профілі постачальників** — конфігурація кожного постачальника для: - - Поріг відмови (кількість відмов до відкриття) - - Тривалість відновлення - - Чутливість визначення межі швидкості - - Експоненціальні параметри відставання +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Обмеження швидкості, які можна редагувати** — параметри системного рівня, які можна налаштувати на інформаційній панелі: - - **Запитів за хвилину (RPM)** — максимальна кількість запитів за хвилину на обліковий запис - - **Мінімальний час між запитами** — мінімальний проміжок у мілісекундах між запитами - - **Max Concurrent Requests** — максимальна кількість одночасних запитів на обліковий запис - - Натисніть **Редагувати**, щоб змінити, потім **Зберегти** або **Скасувати**. Значення зберігаються через API стійкості. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Circuit Breaker** — відстежує збої кожного постачальника та автоматично розмикає ланцюг, коли досягається порогове значення: - - **ЗАКРИТО** (справний) — запити надходять нормально - - **OPEN** — Провайдер тимчасово заблоковано після повторних збоїв - - **HALF_OPEN** — Перевірка, якщо провайдер відновився +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Політики та заблоковані ідентифікатори** — показує статус автоматичного вимикача та заблоковані ідентифікатори з можливістю примусового розблокування. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Автовизначення ліміту швидкості** — відстежує заголовки `429` та `Retry-After`, щоб завчасно уникнути перевищення лімітів швидкості постачальника. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Порада:** Використовуйте кнопку **Скинути все**, щоб очистити всі автоматичні вимикачі та часи відновлення, коли постачальник відновиться після збою. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Експорт/імпорт бази даних +### Database Export / Import -Керуйте резервними копіями бази даних у **Інформаційна панель → Налаштування → Система та сховище**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Дія | Опис | -| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Експорт бази даних** | Завантажує поточну базу даних SQLite як файл `.sqlite` | -| **Експортувати все (.tar.gz)** | Завантажує повний резервний архів, включаючи: базу даних, налаштування, комбінації, з’єднання провайдера (без облікових даних), метадані ключа API | -| **Імпорт бази даних** | Завантажте файл `.sqlite`, щоб замінити поточну базу даних. Автоматично створюється резервна копія перед імпортом | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Перевірка імпорту:** Імпортований файл перевіряється на цілісність (перевірка прагми SQLite), необхідні таблиці (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) і розмір (макс. 100 МБ). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Випадки використання:** +**Use Cases:** -- Перенесення OmniRoute між машинами -- Створення зовнішніх резервних копій для аварійного відновлення -- Спільний доступ до конфігурацій між членами команди (експортувати все → надати доступ до архіву) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Інформаційна панель налаштувань +### Settings Dashboard -Для зручності навігації сторінка налаштувань складається з 5 вкладок: +The settings page is organized into 5 tabs for easy navigation: -| Вкладка | Зміст | -| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| **Безпека** | Налаштування логіна/пароля, контроль IP-доступу, авторизація API для `/models` та блокування постачальника | -| **Маршрутизація** | Глобальна стратегія маршрутизації (6 варіантів), псевдоніми моделей із підстановкою, резервні ланцюжки, комбіновані параметри за замовчуванням | -| **Стійкість** | Профілі постачальників, обмеження швидкості, які можна редагувати, статус автоматичного вимикача, політики та заблоковані ідентифікатори | -| **AI** | Продумана конфігурація бюджету, впровадження глобальної системної підказки, швидка статистика кешу | -| **Розширений** | Глобальна конфігурація проксі (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Управління витратами та бюджетом +### Costs & Budget Management -Доступ через **Інформаційна панель → Витрати**. +Access via **Dashboard → Costs**. -| Вкладка | Призначення | -| ---------- | -------------------------------------------------------------------------------------------------------------------- | -| **Бюджет** | Встановіть ліміти витрат на ключ API за допомогою щоденних/тижневих/місячних бюджетів і відстеження в реальному часі | -| **Ціни** | Перегляд і редагування записів моделі ціноутворення — вартість 1 тис. токенів вводу/виводу на постачальника | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Відстеження вартості:** кожен запит реєструє використання токенів і розраховує вартість за допомогою таблиці цін. Перегляньте розбивку в **Інформаційна панель → Використання** за постачальником, моделлю та ключем API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Транскрипція аудіо +### Audio Transcription -OmniRoute підтримує транскрипцію аудіо через кінцеву точку, сумісну з OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Доступні постачальники: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Підтримувані аудіоформати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Комбіновані стратегії балансування +### Combo Balancing Strategies -Налаштуйте балансування за комбо в **Інформаційна панель → Комбо → Створити/Редагувати → Стратегія**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Стратегія | Опис | -| ----------------------------- | ---------------------------------------------------------------------------------------------- | -| **Кругова система** | Обертає моделі послідовно | -| **Пріоритет** | Завжди пробує першу модель; повертається лише в разі помилки | -| **Випадкове** | Вибирає випадкову модель із комбо для кожного запиту | -| **Зважений** | Маршрути пропорційно на основі призначеної ваги для моделі | -| **Найменш використовуваний** | Маршрути до моделі з найменшою кількістю останніх запитів (використовує комбіновані показники) | -| **Оптимізовано за витратами** | Маршрути до найдешевшої доступної моделі (використовується таблиця цін) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Глобальні стандартні параметри комбінованих маршрутів можна встановити в **Інформаційна панель → Налаштування → Маршрутизація → Стандартні параметри комбінованих маршрутів**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Інформаційна панель здоров'я +### Health Dashboard -Доступ через **Інформаційна панель → Здоров’я**. Огляд стану системи в реальному часі з 6 картками: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Картка | Що це показує | -| -------------------------- | ------------------------------------------------------------------------------------------- | -| **Стан системи** | Час роботи, версія, використання пам’яті, каталог даних | -| **Здоров’я постачальника** | Стан автоматичного вимикача для кожного постачальника (замкнуто/розімкнуто/напіврозімкнуто) | -| **Обмеження швидкості** | Обмеження активної швидкості перезарядки на обліковий запис із часом, що залишився | -| **Активні блокування** | Провайдери, тимчасово заблоковані політикою блокування | -| **Кеш підпису** | Статистика кешу дедуплікації (активні ключі, частота звернень) | -| **Телеметрія затримки** | Агрегація затримок p50/p95/p99 для кожного провайдера | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Професійна порада.** Сторінка «Здоров’я» автоматично оновлюється кожні 10 секунд. Використовуйте картку автоматичного вимикача, щоб визначити, які постачальники мають проблеми. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/vi/API_REFERENCE.md b/docs/i18n/vi/API_REFERENCE.md index 9014605708..b795722c11 100644 --- a/docs/i18n/vi/API_REFERENCE.md +++ b/docs/i18n/vi/API_REFERENCE.md @@ -1,12 +1,12 @@ -# Tham chiếu API +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -Tham chiếu đầy đủ cho tất cả các điểm cuối API OmniRoute. +Complete reference for all OmniRoute API endpoints. --- -## Mục lục +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ Tham chiếu đầy đủ cho tất cả các điểm cuối API OmniRoute. --- -## Hoàn thành cuộc trò chuyện +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### Tiêu đề tùy chỉnh +### Custom Headers -| Tiêu đề | Hướng | Mô tả | -| ------------------------ | -------- | ----------------------------------------------- | -| `X-OmniRoute-No-Cache` | Yêu cầu | Đặt thành `true` để bỏ qua bộ đệm | -| `X-OmniRoute-Progress` | Yêu cầu | Đặt thành `true` cho các sự kiện tiến trình | -| `Idempotency-Key` | Yêu cầu | Khóa khấu trừ (cửa sổ 5s) | -| `X-Request-Id` | Yêu cầu | Khóa khấu trừ thay thế | -| `X-OmniRoute-Cache` | Phản hồi | `HIT` hoặc `MISS` (không phát trực tuyến) | -| `X-OmniRoute-Idempotent` | Phản hồi | `true` nếu được loại bỏ trùng lặp | -| `X-OmniRoute-Progress` | Phản hồi | `enabled` nếu bật tính năng theo dõi tiến trình | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## Nhúng +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -Các nhà cung cấp hiện có: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## Tạo hình ảnh +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -Các nhà cung cấp hiện có: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## Danh sách mô hình +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## Điểm cuối tương thích +## Compatibility Endpoints -| Phương pháp | Đường dẫn | Định dạng | -| ----------- | --------------------------- | ---------------------- | -| ĐĂNG | `/v1/chat/completions` | OpenAI | -| ĐĂNG | `/v1/messages` | Nhân chủng học | -| ĐĂNG | `/v1/responses` | Phản hồi OpenAI | -| ĐĂNG | `/v1/embeddings` | OpenAI | -| ĐĂNG | `/v1/images/generations` | OpenAI | -| NHẬN | `/v1/models` | OpenAI | -| ĐĂNG | `/v1/messages/count_tokens` | Nhân chủng học | -| NHẬN | `/v1beta/models` | Song Tử | -| ĐĂNG | `/v1beta/models/{...path}` | Gemini generateContent | -| ĐĂNG | `/v1/api/chat` | Olama | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### Tuyến đường dành riêng cho nhà cung cấp +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -Tiền tố nhà cung cấp được tự động thêm vào nếu thiếu. Các mô hình không khớp trả về `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## Bộ đệm ngữ nghĩa +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -Ví dụ phản hồi: +Response example: ```json { @@ -162,154 +162,164 @@ Ví dụ phản hồi: --- -## Bảng điều khiển & Quản lý +## Dashboard & Management -### Xác thực +### Authentication -| Điểm cuối | Phương pháp | Mô tả | -| ----------------------------- | ----------- | ---------------------------- | -| `/api/auth/login` | ĐĂNG | Đăng nhập | -| `/api/auth/logout` | ĐĂNG | Đăng xuất | -| `/api/settings/require-login` | NHẬN/ĐẶT | Chuyển đổi yêu cầu đăng nhập | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### Quản lý nhà cung cấp +### Provider Management -| Điểm cuối | Phương pháp | Mô tả | -| ---------------------------- | ------------- | ------------------------------- | -| `/api/providers` | NHẬN/ĐĂNG | Liệt kê/tạo nhà cung cấp | -| `/api/providers/[id]` | NHẬN/ĐẶT/XÓA | Quản lý nhà cung cấp | -| `/api/providers/[id]/test` | ĐĂNG | Kết nối nhà cung cấp thử nghiệm | -| `/api/providers/[id]/models` | NHẬN | Liệt kê mô hình nhà cung cấp | -| `/api/providers/validate` | ĐĂNG | Xác thực cấu hình nhà cung cấp | -| `/api/provider-nodes*` | Khác nhau | Quản lý nút nhà cung cấp | -| `/api/provider-models` | NHẬN/ĐĂNG/XÓA | Mô hình tùy chỉnh | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### Luồng OAuth +### OAuth Flows -| Điểm cuối | Phương pháp | Mô tả | -| -------------------------------- | ----------- | --------------------------------- | -| `/api/oauth/[provider]/[action]` | Khác nhau | OAuth dành riêng cho nhà cung cấp | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### Định tuyến & Cấu hình +### Routing & Config -| Điểm cuối | Phương pháp | Mô tả | -| --------------------- | ----------- | ------------------------------------------- | -| `/api/models/alias` | NHẬN/ĐĂNG | Bí danh mẫu | -| `/api/models/catalog` | NHẬN | Tất cả các mô hình theo nhà cung cấp + loại | -| `/api/combos*` | Khác nhau | Quản lý kết hợp | -| `/api/keys*` | Khác nhau | Quản lý khóa API | -| `/api/pricing` | NHẬN | Giá mẫu | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### Cách sử dụng & Phân tích +### Usage & Analytics -| Điểm cuối | Phương pháp | Mô tả | -| --------------------------- | ----------- | ---------------------------- | -| `/api/usage/history` | NHẬN | Lịch sử sử dụng | -| `/api/usage/logs` | NHẬN | Nhật ký sử dụng | -| `/api/usage/request-logs` | NHẬN | Nhật ký cấp yêu cầu | -| `/api/usage/[connectionId]` | NHẬN | Mức sử dụng trên mỗi kết nối | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### Cài đặt +### Settings -| Điểm cuối | Phương pháp | Mô tả | -| ------------------------------- | ----------- | ------------------------------------ | -| `/api/settings` | NHẬN/ĐẶT | Cài đặt chung | -| `/api/settings/proxy` | NHẬN/ĐẶT | Cấu hình proxy mạng | -| `/api/settings/proxy/test` | ĐĂNG | Kiểm tra kết nối proxy | -| `/api/settings/ip-filter` | NHẬN/ĐẶT | Danh sách cho phép/danh sách chặn IP | -| `/api/settings/thinking-budget` | NHẬN/ĐẶT | Lập luận về ngân sách mã thông báo | -| `/api/settings/system-prompt` | NHẬN/ĐẶT | Lời nhắc hệ thống toàn cầu | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### Giám sát +### Monitoring -| Điểm cuối | Phương pháp | Mô tả | -| ------------------------ | ----------- | -------------------------------- | -| `/api/sessions` | NHẬN | Theo dõi phiên hoạt động | -| `/api/rate-limits` | NHẬN | Giới hạn tỷ lệ cho mỗi tài khoản | -| `/api/monitoring/health` | NHẬN | Kiểm tra sức khỏe | -| `/api/cache` | NHẬN/XÓA | Thống kê bộ nhớ đệm / xóa | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### Sao lưu & Xuất/Nhập +### Backup & Export/Import -| Điểm cuối | Phương pháp | Mô tả | -| --------------------------- | ----------- | ---------------------------------------------------------- | -| `/api/db-backups` | NHẬN | Liệt kê các bản sao lưu có sẵn | -| `/api/db-backups` | ĐƯA | Tạo bản sao lưu thủ công | -| `/api/db-backups` | ĐĂNG | Khôi phục từ bản sao lưu cụ thể | -| `/api/db-backups/export` | NHẬN | Tải xuống cơ sở dữ liệu dưới dạng tệp .sqlite | -| `/api/db-backups/import` | ĐĂNG | Tải lên tệp .sqlite để thay thế cơ sở dữ liệu | -| `/api/db-backups/exportAll` | NHẬN | Tải xuống bản sao lưu đầy đủ dưới dạng kho lưu trữ .tar.gz | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### Đồng bộ đám mây +### Cloud Sync -| Điểm cuối | Phương pháp | Mô tả | -| ---------------------- | ----------- | ----------------------------- | -| `/api/sync/cloud` | Khác nhau | Hoạt động đồng bộ hóa đám mây | -| `/api/sync/initialize` | ĐĂNG | Khởi tạo đồng bộ hóa | -| `/api/cloud/*` | Khác nhau | Quản lý đám mây | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### Công cụ CLI +### CLI Tools -| Điểm cuối | Phương pháp | Mô tả | -| ---------------------------------- | ----------- | ------------------------ | -| `/api/cli-tools/claude-settings` | NHẬN | Trạng thái Claude CLI | -| `/api/cli-tools/codex-settings` | NHẬN | Trạng thái CLI của Codex | -| `/api/cli-tools/droid-settings` | NHẬN | Trạng thái CLI của Droid | -| `/api/cli-tools/openclaw-settings` | NHẬN | Trạng thái CLI OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | NHẬN | Thời gian chạy CLI chung | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -Phản hồi CLI bao gồm: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### Khả năng phục hồi và giới hạn tỷ lệ +### ACP Agents -| Điểm cuối | Phương pháp | Mô tả | -| ----------------------- | ----------- | ------------------------------------------- | -| `/api/resilience` | NHẬN/ĐẶT | Nhận/cập nhật hồ sơ khả năng phục hồi | -| `/api/resilience/reset` | ĐĂNG | Đặt lại bộ ngắt mạch | -| `/api/rate-limits` | NHẬN | Trạng thái giới hạn tỷ lệ cho mỗi tài khoản | -| `/api/rate-limit` | NHẬN | Cấu hình giới hạn tốc độ toàn cầu | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### Đánh giá +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| Điểm cuối | Phương pháp | Mô tả | -| ------------ | ----------- | --------------------------------------- | -| `/api/evals` | NHẬN/ĐĂNG | Liệt kê các bộ đánh giá / đánh giá chạy | +### Resilience & Rate Limits -### Chính sách +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| Điểm cuối | Phương pháp | Mô tả | -| --------------- | ------------- | ----------------------------- | -| `/api/policies` | NHẬN/ĐĂNG/XÓA | Quản lý chính sách định tuyến | +### Evals -### Tuân thủ +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -| Điểm cuối | Phương pháp | Mô tả | -| --------------------------- | ----------- | --------------------------------------- | -| `/api/compliance/audit-log` | NHẬN | Nhật ký kiểm tra tuân thủ (N cuối cùng) | +### Policies -### v1beta (Tương thích với Gemini) +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| Điểm cuối | Phương pháp | Mô tả | -| -------------------------- | ----------- | -------------------------------------- | -| `/v1beta/models` | NHẬN | Liệt kê các mô hình ở định dạng Gemini | -| `/v1beta/models/{...path}` | ĐĂNG | Điểm cuối Gemini `generateContent` | +### Compliance -Các điểm cuối này phản ánh định dạng API của Gemini dành cho những khách hàng mong đợi khả năng tương thích SDK Gemini gốc. +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### API nội bộ/hệ thống +### v1beta (Gemini-Compatible) -| Điểm cuối | Phương pháp | Mô tả | -| --------------- | ----------- | ----------------------------------------------------------------- | -| `/api/init` | NHẬN | Kiểm tra khởi tạo ứng dụng (được sử dụng trong lần chạy đầu tiên) | -| `/api/tags` | NHẬN | Thẻ mô hình tương thích với Ollama (dành cho khách hàng Ollama) | -| `/api/restart` | ĐĂNG | Kích hoạt khởi động lại máy chủ duyên dáng | -| `/api/shutdown` | ĐĂNG | Kích hoạt tắt máy chủ duyên dáng | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **Lưu ý:** Các điểm cuối này được hệ thống sử dụng nội bộ hoặc để tương thích với máy khách Ollama. Chúng thường không được người dùng cuối gọi. +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## Phiên âm âm thanh +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -Phiên âm các tệp âm thanh bằng Deepgram hoặc AssemblyAI. +Transcribe audio files using Deepgram or AssemblyAI. -**Yêu cầu:** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**Trả lời:** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**Nhà cung cấp được hỗ trợ:** `deepgram/nova-3`, `assemblyai/best`. +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**Các định dạng được hỗ trợ:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## Khả năng tương thích của Ollama +## Ollama Compatibility -Đối với khách hàng sử dụng định dạng API của Ollama: +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -Các yêu cầu được dịch tự động giữa Ollama và các định dạng nội bộ. +Requests are automatically translated between Ollama and internal formats. --- -## Đo từ xa +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**Trả lời:** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## Ngân sách +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## Mẫu có sẵn +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## Xử lý yêu cầu +## Request Processing -1. Khách hàng gửi yêu cầu tới `/v1/*` -2. Lệnh gọi trình xử lý tuyến `handleChat`, `handleEmbedding`, `handleAudioTranscription` hoặc `handleImageGeneration` -3. Mô hình đã được giải quyết (nhà cung cấp/mô hình trực tiếp hoặc bí danh/combo) -4. Thông tin xác thực được chọn từ DB cục bộ với tính năng lọc tính khả dụng của tài khoản -5. Để trò chuyện: `handleChatCore` — phát hiện định dạng, dịch, kiểm tra bộ đệm, kiểm tra idempotency -6. Người thực thi nhà cung cấp gửi yêu cầu ngược dòng -7. Phản hồi được dịch trở lại định dạng máy khách (trò chuyện) hoặc trả về nguyên trạng (nhúng/hình ảnh/âm thanh) -8. Việc sử dụng/ghi nhật ký được ghi lại -9. Dự phòng áp dụng cho các lỗi theo quy tắc kết hợp +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -Tham khảo kiến trúc đầy đủ: [link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## Xác thực +## Authentication -- Các tuyến trên trang tổng quan (`/dashboard/*`) sử dụng cookie `auth_token` -- Đăng nhập sử dụng hàm băm mật khẩu đã lưu; dự phòng cho `INITIAL_PASSWORD` -- `requireLogin` có thể chuyển đổi qua `/api/settings/require-login` -- Các tuyến `/v1/*` tùy chọn yêu cầu khóa API Bearer khi `REQUIRE_API_KEY=true` +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/vi/ARCHITECTURE.md b/docs/i18n/vi/ARCHITECTURE.md index aa238ba35b..258d62df53 100644 --- a/docs/i18n/vi/ARCHITECTURE.md +++ b/docs/i18n/vi/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# Kiến trúc OmniRoute +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_Cập nhật lần cuối: 2026-02-18_ +_Last updated: 2026-03-04_ -## Tóm tắt điều hành +## Executive Summary -OmniRoute là cổng định tuyến và bảng thông tin AI cục bộ được xây dựng trên Next.js. -Nó cung cấp một điểm cuối tương thích với OpenAI (`/v1/*`) và định tuyến lưu lượng truy cập trên nhiều nhà cung cấp ngược dòng với tính năng dịch thuật, dự phòng, làm mới mã thông báo và theo dõi việc sử dụng. +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -Khả năng cốt lõi: +Core capabilities: -- Bề mặt API tương thích OpenAI cho CLI/công cụ (28 nhà cung cấp) -- Dịch yêu cầu/phản hồi trên các định dạng của nhà cung cấp -- Dự phòng kết hợp mô hình (chuỗi nhiều mô hình) -- Dự phòng cấp tài khoản (nhiều tài khoản cho mỗi nhà cung cấp) -- Quản lý kết nối nhà cung cấp khóa OAuth + API -- Tạo nhúng thông qua `/v1/embeddings` (6 nhà cung cấp, 9 mô hình) -- Tạo hình ảnh qua `/v1/images/generations` (4 nhà cung cấp, 9 kiểu máy) -- Suy nghĩ phân tích thẻ (`...`) cho các mô hình suy luận -- Dọn dẹp phản hồi để tương thích nghiêm ngặt với OpenAI SDK -- Chuẩn hóa vai trò (nhà phát triển→hệ thống, hệ thống→người dùng) để tương thích giữa các nhà cung cấp -- Chuyển đổi đầu ra có cấu trúc (json_schema → GeminiResponseSchema) -- Tính bền vững cục bộ cho nhà cung cấp, khóa, bí danh, tổ hợp, cài đặt, giá cả -- Theo dõi việc sử dụng/chi phí và ghi nhật ký yêu cầu -- Đồng bộ hóa đám mây tùy chọn để đồng bộ hóa nhiều thiết bị/trạng thái -- Danh sách cho phép/danh sách chặn IP để kiểm soát truy cập API -- Tư duy quản lý ngân sách (passthrough/auto/custom/adaptive) -- Tiêm nhắc nhở hệ thống toàn cầu -- Theo dõi phiên và lấy dấu vân tay -- Giới hạn tỷ lệ nâng cao cho mỗi tài khoản với hồ sơ dành riêng cho nhà cung cấp -- Mô hình ngắt mạch cho khả năng phục hồi của nhà cung cấp -- Bảo vệ đàn chống sét bằng khóa mutex -- Bộ đệm chống trùng lặp yêu cầu dựa trên chữ ký -- Lớp miền: tính khả dụng của mô hình, quy tắc chi phí, chính sách dự phòng, chính sách khóa -- Tính bền vững của trạng thái miền (bộ đệm ghi SQLite dành cho dự phòng, ngân sách, khóa, bộ ngắt mạch) -- Công cụ chính sách để đánh giá yêu cầu tập trung (khóa → ngân sách → dự phòng) -- Yêu cầu đo từ xa với tổng hợp độ trễ p50/p95/p99 -- ID tương quan (X-Request-Id) để theo dõi từ đầu đến cuối -- Ghi nhật ký kiểm tra tuân thủ với tính năng chọn không tham gia trên mỗi khóa API -- Khung đánh giá để đảm bảo chất lượng LLM -- Bảng điều khiển UI có khả năng phục hồi với trạng thái ngắt mạch theo thời gian thực -- Nhà cung cấp OAuth mô-đun (12 mô-đun riêng lẻ trong `src/lib/oauth/providers/`) +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -Mô hình thời gian chạy chính: +Primary runtime model: -- Các tuyến ứng dụng Next.js trong `src/app/api/*` triển khai cả API trang tổng quan và API tương thích -- Lõi định tuyến/SSE được chia sẻ trong `src/sse/*` + `open-sse/*` xử lý việc thực thi, dịch thuật, phát trực tuyến, dự phòng và sử dụng của nhà cung cấp +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## Phạm vi và ranh giới +## Scope and Boundaries -### Trong phạm vi +### In Scope -- Thời gian chạy cổng cục bộ -- API quản lý bảng điều khiển -- Xác thực nhà cung cấp và làm mới mã thông báo -- Yêu cầu dịch và truyền phát SSE -- Trạng thái cục bộ + kiên trì sử dụng -- Phối hợp đồng bộ hóa đám mây tùy chọn +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### Ngoài phạm vi +### Out of Scope -- Triển khai dịch vụ đám mây đằng sau `NEXT_PUBLIC_CLOUD_URL` -- Nhà cung cấp SLA/mặt phẳng điều khiển bên ngoài quy trình cục bộ -- Bản thân các tệp nhị phân CLI bên ngoài (Claude CLI, Codex CLI, v.v.) +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## Bối cảnh hệ thống cấp cao +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## Thành phần thời gian chạy cốt lõi +## Core Runtime Components -## 1) API và Lớp định tuyến (Tuyến ứng dụng Next.js) +## 1) API and Routing Layer (Next.js App Routes) -Các thư mục chính: +Main directories: -- `src/app/api/v1/*` và `src/app/api/v1beta/*` cho các API tương thích -- `src/app/api/*` dành cho API quản lý/cấu hình -- Viết lại tiếp theo trong `next.config.mjs` bản đồ `/v1/*` tới `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -Các tuyến tương thích quan trọng: +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — bao gồm các mô hình tùy chỉnh với `custom: true` -- `src/app/api/v1/embeddings/route.ts` — thế hệ nhúng (6 nhà cung cấp) -- `src/app/api/v1/images/generations/route.ts` — tạo hình ảnh (4+ nhà cung cấp bao gồm Anti Gravity/Nebius) +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — cuộc trò chuyện dành riêng cho từng nhà cung cấp -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — phần nhúng dành riêng cho mỗi nhà cung cấp -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — hình ảnh dành riêng cho mỗi nhà cung cấp +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -Các miền quản lý: +Management domains: -- Xác thực/cài đặt: `src/app/api/auth/*`, `src/app/api/settings/*` -- Nhà cung cấp/kết nối: `src/app/api/providers*` -- Nút nhà cung cấp: `src/app/api/provider-nodes*` -- Mẫu tùy chỉnh: `src/app/api/provider-models` (GET/POST/DELETE) -- Danh mục mẫu: `src/app/api/models/catalog` (GET) -- Cấu hình proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) - OAuth: `src/app/api/oauth/*` -- Khóa/bí danh/combo/giá: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Cách sử dụng: `src/app/api/usage/*` -- Đồng bộ hóa/đám mây: `src/app/api/sync/*`, `src/app/api/cloud/*` -- Người trợ giúp công cụ CLI: `src/app/api/cli-tools/*` -- Bộ lọc IP: `src/app/api/settings/ip-filter` (GET/PUT) -- Ngân sách suy nghĩ: `src/app/api/settings/thinking-budget` (GET/PUT) -- Lời nhắc hệ thống: `src/app/api/settings/system-prompt` (GET/PUT) -- Phiên: `src/app/api/sessions` (GET) -- Giới hạn tỷ lệ: `src/app/api/rate-limits` (GET) -- Khả năng phục hồi: `src/app/api/resilience` (GET/PATCH) — hồ sơ nhà cung cấp, bộ ngắt mạch, trạng thái giới hạn tốc độ -- Đặt lại khả năng phục hồi: `src/app/api/resilience/reset` (POST) — đặt lại bộ ngắt + thời gian hồi chiêu -- Thống kê bộ đệm: `src/app/api/cache/stats` (GET/DELETE) -- Tính sẵn có của mẫu: `src/app/api/models/availability` (GET/POST) -- Đo từ xa: `src/app/api/telemetry/summary` (GET) -- Ngân sách: `src/app/api/usage/budget` (GET/POST) -- Chuỗi dự phòng: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Kiểm tra tuân thủ: `src/app/api/compliance/audit-log` (GET) -- Đánh giá: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Chính sách: `src/app/api/policies` (GET/POST) +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -##2) SSE + Lõi dịch thuật +## 2) SSE + Translation Core -Các mô-đun dòng chảy chính: +Main flow modules: -- Mục nhập: `src/sse/handlers/chat.ts` -- Điều phối cốt lõi: `open-sse/handlers/chatCore.ts` -- Bộ điều hợp thực thi của nhà cung cấp: `open-sse/executors/*` -- Cấu hình nhà cung cấp/phát hiện định dạng: `open-sse/services/provider.ts` -- Phân tích/giải quyết mô hình: `src/sse/services/model.ts`, `open-sse/services/model.ts` -- Logic dự phòng tài khoản: `open-sse/services/accountFallback.ts` -- Đăng ký dịch thuật: `open-sse/translator/index.ts` -- Chuyển đổi luồng: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` -- Trích xuất/chuẩn hóa cách sử dụng: `open-sse/utils/usageTracking.ts` -- Trình phân tích cú pháp thẻ suy nghĩ: `open-sse/utils/thinkTagParser.ts` -- Trình xử lý nhúng: `open-sse/handlers/embeddings.ts` -- Đăng ký nhà cung cấp nhúng: `open-sse/config/embeddingRegistry.ts` -- Trình xử lý tạo ảnh: `open-sse/handlers/imageGeneration.ts` -- Đăng ký nhà cung cấp hình ảnh: `open-sse/config/imageRegistry.ts` -- Khử trùng phản hồi: `open-sse/handlers/responseSanitizer.ts` -- Chuẩn hóa vai trò: `open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -Dịch vụ (logic nghiệp vụ): +Services (business logic): -- Lựa chọn/chấm điểm tài khoản: `open-sse/services/accountSelector.ts` -- Quản lý vòng đời bối cảnh: `open-sse/services/contextManager.ts` -- Thực thi bộ lọc IP: `open-sse/services/ipFilter.ts` -- Theo dõi phiên: `open-sse/services/sessionManager.ts` -- Yêu cầu loại bỏ trùng lặp: `open-sse/services/signatureCache.ts` -- Nội dung nhắc nhở của hệ thống: `open-sse/services/systemPrompt.ts` -- Tư duy quản lý ngân sách: `open-sse/services/thinkingBudget.ts` -- Định tuyến mô hình ký tự đại diện: `open-sse/services/wildcardRouter.ts` -- Quản lý giới hạn tỷ lệ: `open-sse/services/rateLimitManager.ts` -- Cầu dao: `open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -Các mô-đun lớp miền: +Domain layer modules: -- Tính sẵn có của mẫu: `src/lib/domain/modelAvailability.ts` -- Quy tắc chi phí/ngân sách: `src/lib/domain/costRules.ts` -- Chính sách dự phòng: `src/lib/domain/fallbackPolicy.ts` -- Trình giải quyết kết hợp: `src/lib/domain/comboResolver.ts` -- Chính sách khóa: `src/lib/domain/lockoutPolicy.ts` -- Công cụ chính sách: `src/domain/policyEngine.ts` — khóa tập trung → ngân sách → đánh giá dự phòng -- Danh mục mã lỗi: `src/lib/domain/errorCodes.ts` -- ID yêu cầu: `src/lib/domain/requestId.ts` -- Thời gian chờ tìm nạp: `src/lib/domain/fetchTimeout.ts` -- Yêu cầu đo từ xa: `src/lib/domain/requestTelemetry.ts` -- Tuân thủ/kiểm toán: `src/lib/domain/compliance/index.ts` -- Người chạy đánh giá: `src/lib/domain/evalRunner.ts` -- Tính bền vững của trạng thái miền: `src/lib/db/domainState.ts` — SQLite CRUD dành cho chuỗi dự phòng, ngân sách, lịch sử chi phí, trạng thái khóa, bộ ngắt mạch +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -Mô-đun nhà cung cấp OAuth (12 tệp riêng lẻ trong `src/lib/oauth/providers/`): +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- Chỉ số đăng ký: `src/lib/oauth/providers/index.ts` -- Nhà cung cấp cá nhân: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` -- Trình bao bọc mỏng: `src/lib/oauth/providers.ts` — tái xuất từ các mô-đun riêng lẻ +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) Lớp kiên trì +## 3) Persistence Layer -DB trạng thái chính: +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- tệp: `${DATA_DIR}/db.json` (hoặc `$XDG_CONFIG_HOME/omniroute/db.json` khi được đặt, nếu không thì `~/.omniroute/db.json`) -- thực thể: nhà cung cấpKết nối, nhà cung cấpNodes, modelAliases, combo, apiKeys, cài đặt, giá cả, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -Cách sử dụng cơ sở dữ liệu: +Usage persistence: -- `src/lib/usageDb.ts` -- tập tin: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- tuân theo chính sách thư mục cơ sở giống như `localDb` (`DATA_DIR`, sau đó `XDG_CONFIG_HOME/omniroute` khi được đặt) -- được phân tách thành các mô-đun phụ tập trung: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -Cơ sở dữ liệu trạng thái miền (SQLite): +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — Thao tác CRUD cho trạng thái miền -- Các bảng (được tạo trong `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` -- Mẫu bộ đệm ghi qua: Bản đồ trong bộ nhớ có thẩm quyền trong thời gian chạy; các đột biến được ghi đồng bộ vào SQLite; trạng thái được khôi phục từ DB khi khởi động nguội +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -##4) Xác thực + Bề mặt bảo mật +## 4) Auth + Security Surfaces -- Xác thực cookie trang tổng quan: `src/proxy.ts`, `src/app/api/auth/login/route.ts` -- Tạo/xác minh khóa API: `src/shared/utils/apiKey.ts` -- Bí mật của nhà cung cấp vẫn tồn tại trong mục `providerConnections` -- Hỗ trợ proxy gửi đi thông qua `open-sse/utils/proxyFetch.ts` (env vars) và `open-sse/utils/networkProxy.ts` (có thể định cấu hình cho mỗi nhà cung cấp hoặc toàn cầu) +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) Đồng bộ đám mây +## 5) Cloud Sync -- Khởi tạo bộ lập lịch: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` -- Nhiệm vụ định kỳ: `src/shared/services/cloudSyncScheduler.ts` -- Lộ trình điều khiển: `src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## Vòng đời yêu cầu (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## Combo + Luồng dự phòng tài khoản +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Các quyết định dự phòng được điều khiển bởi `open-sse/services/accountFallback.ts` bằng cách sử dụng mã trạng thái và phương pháp phỏng đoán thông báo lỗi. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## Vòng đời giới thiệu OAuth và làm mới mã thông báo +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -Làm mới trong khi lưu lượng truy cập trực tiếp được thực thi bên trong `open-sse/handlers/chatCore.ts` thông qua người thực thi `refreshCredentials()`. +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## Vòng đời đồng bộ hóa đám mây (Bật / Đồng bộ hóa / Tắt) +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -Đồng bộ hóa định kỳ được kích hoạt bởi `CloudSyncScheduler` khi bật đám mây. +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## Mô hình dữ liệu và bản đồ lưu trữ +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -Tệp lưu trữ vật lý: +Physical storage files: -- trạng thái chính: `${DATA_DIR}/db.json` (hoặc `$XDG_CONFIG_HOME/omniroute/db.json` khi được đặt, nếu không thì `~/.omniroute/db.json`) -- số liệu thống kê sử dụng: `${DATA_DIR}/usage.json` -- dòng nhật ký yêu cầu: `${DATA_DIR}/log.txt` -- phiên gỡ lỗi yêu cầu/trình dịch tùy chọn: `/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## Cấu trúc liên kết triển khai +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## Ánh xạ mô-đun (Quyết định quan trọng) +## Module Mapping (Decision-Critical) -### Mô-đun tuyến đường và API +### Route and API Modules -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API tương thích -- `src/app/api/v1/providers/[provider]/*`: các tuyến dành riêng cho mỗi nhà cung cấp (trò chuyện, nội dung nhúng, hình ảnh) -- `src/app/api/providers*`: CRUD của nhà cung cấp, xác thực, kiểm tra -- `src/app/api/provider-nodes*`: quản lý nút tương thích tùy chỉnh -- `src/app/api/provider-models`: quản lý mô hình tùy chỉnh (CRUD) -- `src/app/api/models/catalog`: API danh mục mô hình đầy đủ (tất cả các loại được nhóm theo nhà cung cấp) -- `src/app/api/oauth/*`: Luồng OAuth/mã thiết bị -- `src/app/api/keys*`: vòng đời khóa API cục bộ -- `src/app/api/models/alias`: quản lý bí danh -- `src/app/api/combos*`: quản lý kết hợp dự phòng -- `src/app/api/pricing`: ghi đè giá để tính chi phí -- `src/app/api/settings/proxy`: cấu hình proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: kiểm tra kết nối proxy gửi đi (POST) -- `src/app/api/usage/*`: API sử dụng và nhật ký -- `src/app/api/sync/*` + `src/app/api/cloud/*`: trợ giúp đồng bộ hóa đám mây và hướng tới đám mây -- `src/app/api/cli-tools/*`: trình soạn thảo/kiểm tra cấu hình CLI cục bộ -- `src/app/api/settings/ip-filter`: Danh sách cho phép/danh sách chặn IP (GET/PUT) -- `src/app/api/settings/thinking-budget`: cấu hình ngân sách mã thông báo suy nghĩ (GET/PUT) -- `src/app/api/settings/system-prompt`: lời nhắc hệ thống toàn cầu (GET/PUT) -- `src/app/api/sessions`: danh sách phiên hoạt động (GET) -- `src/app/api/rate-limits`: trạng thái giới hạn tỷ lệ cho mỗi tài khoản (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### Lõi định tuyến và thực thi +### Routing and Execution Core -- `src/sse/handlers/chat.ts`: phân tích cú pháp yêu cầu, xử lý kết hợp, vòng lặp chọn tài khoản -- `open-sse/handlers/chatCore.ts`: dịch, gửi người thực thi, xử lý thử lại/làm mới, thiết lập luồng -- `open-sse/executors/*`: hành vi định dạng và mạng dành riêng cho nhà cung cấp +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### Bộ chuyển đổi định dạng và đăng ký dịch thuật +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`: đăng ký dịch giả và điều phối -- Yêu cầu người dịch: `open-sse/translator/request/*` -- Người dịch phản hồi: `open-sse/translator/response/*` -- Hằng định dạng: `open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### Kiên trì +### Persistence -- `src/lib/localDb.ts`: trạng thái/cấu hình liên tục -- `src/lib/usageDb.ts`: lịch sử sử dụng và nhật ký yêu cầu luân phiên +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## Bảo hiểm người thực thi nhà cung cấp (Mẫu chiến lược) +## Provider Executor Coverage (Strategy Pattern) -Mỗi nhà cung cấp có một trình thực thi chuyên biệt mở rộng `BaseExecutor` (trong `open-sse/executors/base.ts`), cung cấp việc xây dựng URL, xây dựng tiêu đề, thử lại với thời gian chờ theo cấp số nhân, móc làm mới thông tin xác thực và phương thức điều phối `execute()`. +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| Người thi hành | (Các) nhà cung cấp | Xử lý đặc biệt | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Cấu hình URL/tiêu đề động cho mỗi nhà cung cấp | -| `AntigravityExecutor` | Google phản lực hấp dẫn | ID dự án/phiên tùy chỉnh, Thử lại sau khi phân tích cú pháp | -| `CodexExecutor` | OpenAI Codex | Đưa vào các hướng dẫn hệ thống, buộc nỗ lực suy luận | -| `CursorExecutor` | IDE con trỏ | Giao thức ConnectRPC, mã hóa Protobuf, ký yêu cầu qua tổng kiểm tra | -| `GithubExecutor` | Phi công phụ GitHub | Làm mới mã thông báo Copilot, tiêu đề bắt chước VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Định dạng nhị phân AWS EventStream → Chuyển đổi SSE | -| `GeminiCLIExecutor` | Song Tử CLI | Chu kỳ làm mới mã thông báo Google OAuth | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -Tất cả các nhà cung cấp khác (bao gồm các nút tương thích tùy chỉnh) đều sử dụng `DefaultExecutor`. +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## Ma trận tương thích của nhà cung cấp +## Provider Compatibility Matrix -| Nhà cung cấp | Định dạng | Xác thực | Truyền phát | Không phát trực tuyến | Làm mới mã thông báo | API sử dụng | -| ------------------- | --------------- | ----------------------------- | ---------------- | --------------------- | -------------------- | ----------------------------- | -| Claude | Claude | Khóa API / OAuth | ✅ | ✅ | ✅ | ⚠️ Chỉ dành cho quản trị viên | -| Song Tử | song tử | Khóa API / OAuth | ✅ | ✅ | ✅ | ⚠️ Bảng điều khiển đám mây | -| Song Tử CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Bảng điều khiển đám mây | -| Phản lực hấp dẫn | phản trọng lực | OAuth | ✅ | ✅ | ✅ | ✅ API hạn ngạch đầy đủ | -| OpenAI | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| Codex | phản hồi openai | OAuth | ✅ ép buộc | ❌ | ✅ | ✅ Giới hạn tỷ lệ | -| Phi công phụ GitHub | mở | OAuth + Mã thông báo đồng lái | ✅ | ✅ | ✅ | ✅ Ảnh chụp nhanh hạn ngạch | -| Con trỏ | con trỏ | Tổng kiểm tra tùy chỉnh | ✅ | ✅ | ❌ | ❌ | -| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Giới hạn sử dụng | -| Qwen | mở | OAuth | ✅ | ✅ | ✅ | ⚠️ Theo yêu cầu | -| iFlow | mở | OAuth (Cơ bản) | ✅ | ✅ | ✅ | ⚠️ Theo yêu cầu | -| OpenRouter | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | Claude | Khóa API | ✅ | ✅ | ❌ | ❌ | -| DeepSeek | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| Groq | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| Mistral | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| Lúng túng | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| Cùng AI | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| Pháo hoa AI | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| Não | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| Kết hợp | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | mở | Khóa API | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## Phạm vi dịch định dạng +## Format Translation Coverage -Các định dạng nguồn được phát hiện bao gồm: +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -Các định dạng mục tiêu bao gồm: +Target formats include: -- Trò chuyện/Phản hồi OpenAI +- OpenAI chat/Responses - Claude -- Phong bì Song Tử/Song Tử-CLI/Phản trọng lực +- Gemini/Gemini-CLI/Antigravity envelope - Kiro -- Con trỏ +- Cursor -Các bản dịch sử dụng **OpenAI làm định dạng trung tâm** — tất cả các chuyển đổi đều thông qua OpenAI dưới dạng trung gian: +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -Các bản dịch được chọn linh hoạt dựa trên hình dạng tải trọng nguồn và định dạng mục tiêu của nhà cung cấp. +Translations are selected dynamically based on source payload shape and provider target format. -Các lớp xử lý bổ sung trong quy trình dịch thuật: +Additional processing layers in the translation pipeline: -- **Sạch hóa phản hồi** — Loại bỏ các trường không chuẩn khỏi phản hồi ở định dạng OpenAI (cả phát trực tuyến và không phát trực tuyến) để đảm bảo tuân thủ nghiêm ngặt SDK -- **Chuẩn hóa vai trò** — Chuyển đổi `developer` → `system` cho các mục tiêu không phải OpenAI; hợp nhất `system` → `user` cho các mô hình từ chối vai trò hệ thống (GLM, ERNIE) -- **Suy nghĩ trích xuất thẻ** — Phân tích cú pháp `...` chặn nội dung vào trường `reasoning_content` -- **Đầu ra có cấu trúc** — Chuyển đổi OpenAI `response_format.json_schema` thành `responseMimeType` + `responseSchema` của Gemini +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## Điểm cuối API được hỗ trợ +## Supported API Endpoints -| Điểm cuối | Định dạng | Người xử lý | -| -------------------------------------------------- | ---------------------------- | ------------------------------------------------------------- | -| `POST /v1/chat/completions` | Trò chuyện OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Tin nhắn Claude | Trình xử lý tương tự (tự động phát hiện) | -| `POST /v1/responses` | Phản hồi OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Nhúng OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Danh sách mô hình | Tuyến đường API | -| `POST /v1/images/generations` | Hình ảnh OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Danh sách mô hình | Tuyến đường API | -| `POST /v1/providers/{provider}/chat/completions` | Trò chuyện OpenAI | Dành riêng cho mỗi nhà cung cấp với xác thực mô hình | -| `POST /v1/providers/{provider}/embeddings` | Nhúng OpenAI | Dành riêng cho mỗi nhà cung cấp với xác thực mô hình | -| `POST /v1/providers/{provider}/images/generations` | Hình ảnh OpenAI | Dành riêng cho mỗi nhà cung cấp với xác thực mô hình | -| `POST /v1/messages/count_tokens` | Số lượng mã thông báo Claude | Tuyến đường API | -| `GET /v1/models` | Danh sách mô hình OpenAI | Tuyến API (trò chuyện + nhúng + hình ảnh + mô hình tùy chỉnh) | -| `GET /api/models/catalog` | Danh mục | Tất cả các mô hình được nhóm theo nhà cung cấp + loại | -| `POST /v1beta/models/*:streamGenerateContent` | Song Tử bản địa | Tuyến đường API | -| `GET/PUT/DELETE /api/settings/proxy` | Cấu hình proxy | Cấu hình proxy mạng | -| `POST /api/settings/proxy/test` | Kết nối proxy | Điểm cuối kiểm tra tình trạng/kết nối proxy | -| `GET/POST/DELETE /api/provider-models` | Mô hình tùy chỉnh | Quản lý mô hình tùy chỉnh cho mỗi nhà cung cấp | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## Trình xử lý bỏ qua +## Bypass Handler -Trình xử lý bỏ qua (`open-sse/utils/bypassHandler.ts`) chặn các yêu cầu "loại bỏ" đã biết từ Claude CLI — ping khởi động, trích xuất tiêu đề và số lượng mã thông báo — và trả về **phản hồi giả** mà không tiêu tốn mã thông báo của nhà cung cấp ngược dòng. Điều này chỉ được kích hoạt khi `User-Agent` chứa `claude-cli`. +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## Yêu cầu đường dẫn trình ghi nhật ký +## Request Logger Pipeline -Trình ghi nhật ký yêu cầu (`open-sse/utils/requestLogger.ts`) cung cấp quy trình ghi nhật ký gỡ lỗi gồm 7 giai đoạn, bị tắt theo mặc định, được bật qua `ENABLE_REQUEST_LOGS=true`: +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -Các tệp được ghi vào `/logs//` cho mỗi phiên yêu cầu. +Files are written to `/logs//` for each request session. -## Các chế độ thất bại và khả năng phục hồi +## Failure Modes and Resilience -## 1) Tính khả dụng của tài khoản/nhà cung cấp +## 1) Account/Provider Availability -- thời gian hồi chiêu của tài khoản nhà cung cấp đối với các lỗi tạm thời/tỷ lệ/xác thực -- dự phòng tài khoản trước khi yêu cầu không thành công -- dự phòng mô hình kết hợp khi đường dẫn mô hình/nhà cung cấp hiện tại đã hết +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) Mã thông báo hết hạn +## 2) Token Expiry -- kiểm tra trước và làm mới bằng cách thử lại đối với các nhà cung cấp có thể làm mới -- Thử lại 401/403 sau lần thử làm mới trong đường dẫn lõi +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -##3) An toàn khi truyền phát +## 3) Stream Safety -- bộ điều khiển luồng nhận biết ngắt kết nối -- luồng dịch với tính năng xóa cuối luồng và xử lý `[DONE]` -- dự phòng ước tính sử dụng khi thiếu siêu dữ liệu sử dụng của nhà cung cấp +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) Suy giảm đồng bộ đám mây +## 4) Cloud Sync Degradation -- lỗi đồng bộ hóa xuất hiện nhưng thời gian chạy cục bộ vẫn tiếp tục -- bộ lập lịch có logic có khả năng thử lại, nhưng việc thực thi định kỳ hiện gọi đồng bộ hóa một lần thử theo mặc định +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) Toàn vẹn dữ liệu +## 5) Data Integrity -- Di chuyển/sửa chữa hình dạng DB cho các khóa bị thiếu -- các biện pháp bảo vệ đặt lại JSON bị hỏng cho localDb và useDb +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## Tín hiệu quan sát và hoạt động +## Observability and Operational Signals -Nguồn hiển thị thời gian chạy: +Runtime visibility sources: -- nhật ký bảng điều khiển từ `src/sse/utils/logger.ts` -- tổng mức sử dụng theo yêu cầu trong `usage.json` -- nhật ký trạng thái yêu cầu bằng văn bản trong `log.txt` -- nhật ký dịch/yêu cầu sâu tùy chọn trong `logs/` khi `ENABLE_REQUEST_LOGS=true` -- điểm cuối sử dụng trang tổng quan (`/api/usage/*`) để sử dụng giao diện người dùng +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## Ranh giới nhạy cảm về bảo mật +## Security-Sensitive Boundaries -- Bí mật JWT (`JWT_SECRET`) bảo mật việc xác minh/ký cookie phiên bảng điều khiển -- Dự phòng mật khẩu ban đầu (`INITIAL_PASSWORD`, mặc định `123456`) phải được ghi đè trong quá trình triển khai thực tế -- Khóa API Bí mật HMAC (`API_KEY_SECRET`) bảo mật định dạng khóa API cục bộ được tạo -- Bí mật của nhà cung cấp (khóa API/mã thông báo) được lưu giữ trong DB cục bộ và phải được bảo vệ ở cấp hệ thống tệp -- Điểm cuối đồng bộ hóa đám mây dựa vào ngữ nghĩa xác thực khóa API + id máy +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## Ma trận môi trường và thời gian chạy +## Environment and Runtime Matrix -Các biến môi trường được mã sử dụng tích cực: +Environment variables actively used by code: -- Ứng dụng/xác thực: `JWT_SECRET`, `INITIAL_PASSWORD` -- Bộ nhớ: `DATA_DIR` -- Hành vi của nút tương thích: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Ghi đè cơ sở lưu trữ tùy chọn (Linux/macOS khi `DATA_DIR` không được đặt): `XDG_CONFIG_HOME` -- Băm bảo mật: `API_KEY_SECRET`, `MACHINE_ID_SALT` -- Ghi nhật ký: `ENABLE_REQUEST_LOGS` -- URL đồng bộ hóa/đám mây: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` -- Proxy gửi đi: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` và các biến thể chữ thường -- Cờ tính năng SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Trình trợ giúp nền tảng/thời gian chạy (không phải cấu hình dành riêng cho ứng dụng): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## Ghi chú kiến trúc đã biết +## Known Architectural Notes -1. `usageDb` và `localDb` hiện chia sẻ cùng một chính sách thư mục cơ sở (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) với việc di chuyển tệp cũ. -2. `/api/v1/route.ts` trả về danh sách mô hình tĩnh và không phải là nguồn mô hình chính được `/v1/models` sử dụng. -3. Trình ghi yêu cầu ghi toàn bộ tiêu đề/nội dung khi được bật; coi thư mục nhật ký là nhạy cảm. -4. Hoạt động của đám mây phụ thuộc vào `NEXT_PUBLIC_BASE_URL` chính xác và khả năng tiếp cận điểm cuối của đám mây. -5. Thư mục `open-sse/` được xuất bản dưới dạng `@omniroute/open-sse` **gói không gian làm việc npm**. Mã nguồn nhập nó qua `@omniroute/open-sse/...` (được giải quyết bởi Next.js `transpilePackages`). Đường dẫn tệp trong tài liệu này vẫn sử dụng tên thư mục `open-sse/` để đảm bảo tính nhất quán. -6. Các biểu đồ trong trang tổng quan sử dụng **Recharts** (dựa trên SVG) để hiển thị trực quan hóa phân tích tương tác, có thể truy cập (biểu đồ thanh sử dụng mô hình, bảng phân tích nhà cung cấp với tỷ lệ thành công). -7. Kiểm tra E2E sử dụng **Playwright** (`tests/e2e/`), chạy qua `npm run test:e2e`. Kiểm thử đơn vị sử dụng **Trình chạy thử nghiệm Node.js** (`tests/unit/`), chạy qua `npm run test:plan3`. Mã nguồn trong `src/` là **TypeScript** (`.ts`/`.tsx`); không gian làm việc `open-sse/` vẫn là JavaScript (`.js`). -8. Trang cài đặt được tổ chức thành 5 tab: Bảo mật, Định tuyến (6 chiến lược toàn cầu: điền trước, quay vòng, p2c, ngẫu nhiên, ít sử dụng nhất, tối ưu hóa chi phí), Khả năng phục hồi (giới hạn tốc độ có thể chỉnh sửa, ngắt mạch, chính sách), AI (ngân sách suy nghĩ, lời nhắc hệ thống, bộ nhớ đệm nhắc nhở), Nâng cao (proxy). +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## Danh sách kiểm tra xác minh hoạt động +## Operational Verification Checklist -- Xây dựng từ nguồn: `npm run build` -- Xây dựng Docker image: `docker build -t omniroute .` -- Bắt đầu dịch vụ và xác minh: +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- URL cơ sở mục tiêu CLI phải là `http://:20128/v1` khi `PORT=20128` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/vi/CODEBASE_DOCUMENTATION.md b/docs/i18n/vi/CODEBASE_DOCUMENTATION.md index c912b57dea..303880c198 100644 --- a/docs/i18n/vi/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/vi/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -# omniroute — Tài liệu cơ sở mã +# omniroute — Codebase Documentation -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) -> Hướng dẫn toàn diện, thân thiện với người mới bắt đầu về bộ định tuyến proxy AI đa nhà cung cấp **omnroute**. +> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. Omniroute là gì? +## 1. What Is omniroute? -omniroute là **bộ định tuyến proxy** nằm giữa các máy khách AI (Claude CLI, Codex, Cursor IDE, v.v.) và các nhà cung cấp AI (Anthropic, Google, OpenAI, AWS, GitHub, v.v.). Nó giải quyết một vấn đề lớn: +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **Các ứng dụng khách AI khác nhau nói những "ngôn ngữ" (định dạng API) khác nhau và các nhà cung cấp AI khác nhau cũng mong đợi những "ngôn ngữ" khác nhau.** omniroute dịch tự động giữa chúng. +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -Hãy nghĩ về nó giống như một dịch giả phổ quát tại Liên hợp quốc - bất kỳ đại biểu nào cũng có thể nói bất kỳ ngôn ngữ nào và người phiên dịch sẽ chuyển đổi ngôn ngữ đó cho bất kỳ đại biểu nào khác. +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. Tổng quan về kiến trúc +## 2. Architecture Overview ```mermaid graph LR @@ -61,20 +61,20 @@ graph LR H -.-> G ``` -### Nguyên tắc cốt lõi: Dịch Hub-and-Spoke +### Core Principle: Hub-and-Spoke Translation -Tất cả các bản dịch định dạng đều đi qua **định dạng OpenAI làm trung tâm**: +All format translation passes through **OpenAI format as the hub**: ``` Client Format → [OpenAI Hub] → Provider Format (request) Provider Format → [OpenAI Hub] → Client Format (response) ``` -Điều này có nghĩa là bạn chỉ cần **N người dịch** (một người cho mỗi định dạng) thay vì **N²** (mỗi cặp). +This means you only need **N translators** (one per format) instead of **N²** (every pair). --- -## 3. Cấu trúc dự án +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. Phân tích theo từng mô-đun +## 4. Module-by-Module Breakdown -### Cấu hình 4.1 (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) -**nguồn tin cậy duy nhất** cho tất cả cấu hình của nhà cung cấp. +The **single source of truth** for all provider configuration. -| Tập tin | Mục đích | -| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` có URL cơ sở, thông tin xác thực OAuth (mặc định), tiêu đề và lời nhắc hệ thống mặc định cho mọi nhà cung cấp. Đồng thời xác định `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` và `SKIP_PATTERNS`. | -| `credentialLoader.ts` | Tải thông tin xác thực bên ngoài từ `data/provider-credentials.json` và hợp nhất chúng theo giá trị mặc định được mã hóa cứng trong `PROVIDERS`. Giữ bí mật ngoài tầm kiểm soát nguồn trong khi vẫn duy trì khả năng tương thích ngược. | -| `providerModels.ts` | Cơ quan đăng ký mô hình trung tâm: bí danh của nhà cung cấp bản đồ → ID mô hình. Các chức năng như `getModels()`, `getProviderByAlias()`. | -| `codexInstructions.ts` | Hướng dẫn hệ thống được đưa vào các yêu cầu Codex (chỉnh sửa các ràng buộc, quy tắc hộp cát, chính sách phê duyệt). | -| `defaultThinkingSignature.ts` | Chữ ký "suy nghĩ" mặc định cho mô hình Claude và Gemini. | -| `ollamaModels.ts` | Định nghĩa lược đồ cho các mô hình Ollama cục bộ (tên, kích thước, họ, lượng tử hóa). | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### Luồng tải thông tin xác thực +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 Người thực thi (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -Người thực thi gói gọn **logic dành riêng cho nhà cung cấp** bằng cách sử dụng **Mẫu chiến lược**. Mỗi người thi hành ghi đè các phương thức cơ bản nếu cần. +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| Người thi hành | Nhà cung cấp | Chuyên ngành chính | -| ---------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `base.ts` | — | Cơ sở trừu tượng: Xây dựng URL, tiêu đề, logic thử lại, làm mới thông tin xác thực | -| `default.ts` | Claude, Song Tử, OpenAI, GLM, Kimi, MiniMax | Làm mới mã thông báo OAuth chung cho các nhà cung cấp tiêu chuẩn | -| `antigravity.ts` | Mã đám mây của Google | Tạo ID dự án/phiên, dự phòng nhiều URL, phân tích cú pháp thử lại tùy chỉnh từ thông báo lỗi ("đặt lại sau 2h7m23 giây") | -| `cursor.ts` | IDE con trỏ | **Phức tạp nhất**: Xác thực tổng kiểm tra SHA-256, mã hóa yêu cầu Protobuf, EventStream nhị phân → phân tích cú pháp phản hồi SSE | -| `codex.ts` | OpenAI Codex | Đưa vào các hướng dẫn hệ thống, quản lý các cấp độ tư duy, loại bỏ các tham số không được hỗ trợ | -| `gemini-cli.ts` | Google Song Tử CLI | Xây dựng URL tùy chỉnh (`streamGenerateContent`), làm mới mã thông báo Google OAuth | -| `github.ts` | Phi công phụ GitHub | Hệ thống mã thông báo kép (GitHub OAuth + mã thông báo Copilot), bắt chước tiêu đề VSCode | -| `kiro.ts` | AWS CodeWhisperer | Phân tích cú pháp nhị phân AWS EventStream, khung sự kiện AMZN, ước tính mã thông báo | -| `index.ts` | — | Nhà máy: tên nhà cung cấp bản đồ → lớp người thực thi, với dự phòng mặc định | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### Trình xử lý 4.3 (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**Lớp điều phối** — điều phối việc dịch, thực thi, phát trực tuyến và xử lý lỗi. +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| Tập tin | Mục đích | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Dàn nhạc trung tâm** (~600 dòng). Xử lý vòng đời yêu cầu hoàn chỉnh: phát hiện định dạng → dịch → gửi người thực thi → phản hồi truyền trực tuyến/không truyền phát → làm mới mã thông báo → xử lý lỗi → ghi nhật ký sử dụng. | -| `responsesHandler.ts` | Bộ điều hợp cho API phản hồi của OpenAI: chuyển đổi định dạng Phản hồi → Hoàn thành cuộc trò chuyện → gửi tới `chatCore` → chuyển đổi SSE trở lại định dạng Phản hồi. | -| `embeddings.ts` | Trình xử lý tạo nhúng: giải quyết mô hình nhúng → nhà cung cấp, gửi tới API của nhà cung cấp, trả về phản hồi nhúng tương thích với OpenAI. Hỗ trợ hơn 6 nhà cung cấp. | -| `imageGeneration.ts` | Trình xử lý tạo hình ảnh: phân giải mô hình hình ảnh → nhà cung cấp, hỗ trợ các chế độ tương thích với OpenAI, hình ảnh Gemini (Chống trọng lực) và dự phòng (Nebius). Trả về hình ảnh base64 hoặc URL. | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### Vòng đời yêu cầu (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### Dịch vụ 4.4 (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -Logic nghiệp vụ hỗ trợ các trình xử lý và thực thi. +Business logic that supports the handlers and executors. -| Tập tin | Mục đích | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Phát hiện định dạng** (`detectFormat`): phân tích cấu trúc nội dung yêu cầu để xác định các định dạng Claude/OpenAI/Gemini/AntiGravity/Responses (bao gồm `max_tokens` heuristic cho Claude). Ngoài ra: xây dựng URL, xây dựng tiêu đề, chuẩn hóa cấu hình tư duy. Hỗ trợ các nhà cung cấp động `openai-compatible-*` và `anthropic-compatible-*`. | -| `model.ts` | Phân tích cú pháp chuỗi mô hình (`claude/model-name` → `{provider: "claude", model: "model-name"}`), phân giải bí danh với khả năng phát hiện xung đột, dọn dẹp đầu vào (từ chối ký tự điều khiển/truyền tải đường dẫn) và phân giải thông tin mô hình với hỗ trợ getter bí danh không đồng bộ. | -| `accountFallback.ts` | Xử lý giới hạn tốc độ: thời gian chờ theo cấp số nhân (1 giây → 2 giây → 4 giây → tối đa 2 phút), quản lý thời gian hồi chiêu của tài khoản, phân loại lỗi (lỗi nào kích hoạt dự phòng so với không). | -| `tokenRefresh.ts` | Làm mới mã thông báo OAuth cho **mọi nhà cung cấp**: Google (Gemini, AntiGravity), Claude, Codex, Qwen, iFlow, GitHub (Mã thông báo kép OAuth + Copilot), Kiro (AWS SSO OIDC + Social Auth). Bao gồm bộ nhớ đệm chống trùng lặp lời hứa trong quá trình thực hiện và thử lại với thời gian chờ theo cấp số nhân. | -| `combo.ts` | **Mô hình kết hợp**: chuỗi mô hình dự phòng. Nếu mô hình A không thành công với lỗi đủ điều kiện dự phòng, hãy thử mô hình B, sau đó là C, v.v. Trả về mã trạng thái ngược dòng thực tế. | -| `usage.ts` | Tìm nạp hạn ngạch/dữ liệu sử dụng từ API của nhà cung cấp (hạn ngạch GitHub Copilot, hạn ngạch mô hình AntiGravity, giới hạn tốc độ Codex, phân tích sử dụng Kiro, cài đặt Claude). | -| `accountSelector.ts` | Lựa chọn tài khoản thông minh với thuật toán tính điểm: xem xét mức độ ưu tiên, trạng thái sức khỏe, vị trí luân chuyển và trạng thái thời gian hồi chiêu để chọn tài khoản tối ưu cho từng yêu cầu. | -| `contextManager.ts` | Quản lý vòng đời ngữ cảnh yêu cầu: tạo và theo dõi các đối tượng ngữ cảnh theo yêu cầu bằng siêu dữ liệu (ID yêu cầu, dấu thời gian, thông tin nhà cung cấp) để gỡ lỗi và ghi nhật ký. | -| `ipFilter.ts` | Kiểm soát truy cập dựa trên IP: hỗ trợ chế độ danh sách cho phép và danh sách chặn. Xác thực IP của khách hàng dựa trên các quy tắc đã định cấu hình trước khi xử lý các yêu cầu API. | -| `sessionManager.ts` | Theo dõi phiên bằng dấu vân tay của khách hàng: theo dõi các phiên hoạt động bằng cách sử dụng mã định danh khách hàng được băm, theo dõi số lượng yêu cầu và cung cấp số liệu phiên. | -| `signatureCache.ts` | Bộ đệm chống trùng lặp dựa trên chữ ký yêu cầu: ngăn chặn các yêu cầu trùng lặp bằng cách lưu vào bộ đệm các chữ ký yêu cầu gần đây và trả về các phản hồi được lưu trong bộ nhớ đệm cho các yêu cầu giống hệt nhau trong một khoảng thời gian. | -| `systemPrompt.ts` | Chèn lời nhắc hệ thống toàn cầu: thêm vào trước hoặc thêm lời nhắc hệ thống có thể định cấu hình cho tất cả các yêu cầu, với khả năng xử lý khả năng tương thích của mỗi nhà cung cấp. | -| `thinkingBudget.ts` | Quản lý ngân sách mã thông báo lý luận: hỗ trợ các chế độ chuyển tiếp, tự động (cấu hình tư duy dải), tùy chỉnh (ngân sách cố định) và chế độ thích ứng (theo tỷ lệ phức tạp) để kiểm soát mã thông báo suy nghĩ/lý luận. | -| `wildcardRouter.ts` | Định tuyến mẫu mô hình ký tự đại diện: phân giải các mẫu ký tự đại diện (ví dụ: `*/claude-*`) thành các cặp nhà cung cấp/mô hình cụ thể dựa trên tính khả dụng và mức độ ưu tiên. | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### Chống trùng lặp làm mới mã thông báo +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### Máy trạng thái dự phòng tài khoản +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### Chuỗi Model Combo +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### Trình dịch 4.5 (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -**Công cụ dịch định dạng** sử dụng hệ thống plugin tự đăng ký. +The **format translation engine** using a self-registering plugin system. -#### Kiến trúc +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| Thư mục | Tập tin | Mô tả | -| ------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 dịch giả | Chuyển đổi nội dung yêu cầu giữa các định dạng. Mỗi tệp tự đăng ký thông qua `register(from, to, fn)` khi nhập. | -| `response/` | 7 dịch giả | Chuyển đổi các đoạn phản hồi phát trực tuyến giữa các định dạng. Xử lý các loại sự kiện SSE, khối suy nghĩ, lệnh gọi công cụ. | -| `helpers/` | 6 người giúp việc | Các tiện ích được chia sẻ: `claudeHelper` (trích xuất lời nhắc hệ thống, cấu hình tư duy), `geminiHelper` (ánh xạ các bộ phận/nội dung), `openaiHelper` (lọc định dạng), `toolCallHelper` (tạo ID, chèn phản hồi bị thiếu), `maxTokensHelper`, `responsesApiHelper`. | -| `index.ts` | — | Công cụ dịch thuật: `translateRequest()`, `translateResponse()`, quản lý nhà nước, đăng ký. | -| `formats.ts` | — | Hằng số định dạng: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### Thiết kế Key: Plugin tự đăng ký +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 Tiện ích (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| Tập tin | Mục đích | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | -| `error.ts` | Xây dựng phản hồi lỗi (định dạng tương thích với OpenAI), phân tích lỗi ngược dòng, trích xuất thời gian thử lại AntiGravity từ các thông báo lỗi, phát trực tuyến lỗi SSE. | -| `stream.ts` | **SSE Transform Stream** — đường truyền phát trực tuyến cốt lõi. Hai chế độ: `TRANSLATE` (dịch định dạng đầy đủ) và `PASSTHROUGH` (chuẩn hóa + trích xuất cách sử dụng). Xử lý việc lưu vào bộ đệm, ước tính mức sử dụng, theo dõi độ dài nội dung. Các phiên bản bộ mã hóa/giải mã mỗi luồng tránh trạng thái chia sẻ. | -| `streamHelpers.ts` | Các tiện ích SSE cấp thấp: `parseSSELine` (không chịu khoảng trắng), `hasValuableContent` (lọc các đoạn trống cho OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (tuần tự hóa SSE nhận biết định dạng với tính năng dọn dẹp `perf_metrics`). | -| `usageTracking.ts` | Trích xuất mức sử dụng mã thông báo từ bất kỳ định dạng nào (Claude/OpenAI/Gemini/Responses), ước tính với tỷ lệ ký tự trên mỗi mã thông báo của công cụ/thông báo riêng biệt, bổ sung bộ đệm (giới hạn an toàn 2000 mã thông báo), lọc trường theo định dạng cụ thể, ghi nhật ký bảng điều khiển với màu ANSI. | -| `requestLogger.ts` | Ghi nhật ký yêu cầu dựa trên tệp (chọn tham gia qua `ENABLE_REQUEST_LOGS=true`). Tạo thư mục phiên với các tệp được đánh số: `1_req_client.json` → `7_res_client.txt`. Tất cả I/O đều không đồng bộ (bắn và quên). Mặt nạ tiêu đề nhạy cảm. | -| `bypassHandler.ts` | Chặn các mẫu cụ thể từ Claude CLI (trích xuất tiêu đề, khởi động, đếm) và trả về các phản hồi giả mạo mà không cần gọi cho bất kỳ nhà cung cấp nào. Hỗ trợ cả phát trực tuyến và không phát trực tuyến. Cố ý giới hạn trong phạm vi Claude CLI. | -| `networkProxy.ts` | Phân giải URL proxy gửi đi cho một nhà cung cấp nhất định với mức độ ưu tiên: cấu hình dành riêng cho nhà cung cấp → cấu hình chung → biến môi trường (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Hỗ trợ loại trừ `NO_PROXY`. Cấu hình bộ nhớ đệm trong 30 giây. | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### Đường ống truyền phát SSE +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### Cấu trúc phiên ghi nhật ký yêu cầu +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 Lớp ứng dụng (`src/`) +### 4.7 Application Layer (`src/`) -| Thư mục | Mục đích | -| ------------- | ------------------------------------------------------------------------------------------- | -| `src/app/` | Giao diện người dùng web, tuyến API, phần mềm trung gian Express, trình xử lý gọi lại OAuth | -| `src/lib/` | Truy cập cơ sở dữ liệu (`localDb.ts`, `usageDb.ts`), xác thực, chia sẻ | -| `src/mitm/` | Tiện ích proxy trung gian để chặn lưu lượng truy cập của nhà cung cấp | -| `src/models/` | Định nghĩa mô hình cơ sở dữ liệu | -| `src/shared/` | Trình bao bọc xung quanh các hàm open-sse (nhà cung cấp, luồng, lỗi, v.v.) | -| `src/sse/` | Trình xử lý điểm cuối SSE kết nối thư viện open-sse với các tuyến Express | -| `src/store/` | Quản lý trạng thái ứng dụng | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### Các tuyến API đáng chú ý +#### Notable API Routes -| Tuyến đường | Phương pháp | Mục đích | -| --------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------- | -| `/api/provider-models` | NHẬN/ĐĂNG/XÓA | CRUD cho các mô hình tùy chỉnh cho mỗi nhà cung cấp | -| `/api/models/catalog` | NHẬN | Danh mục tổng hợp của tất cả các mô hình (trò chuyện, nhúng, hình ảnh, tùy chỉnh) được nhóm theo nhà cung cấp | -| `/api/settings/proxy` | NHẬN/ĐẶT/XÓA | Cấu hình proxy gửi đi theo cấp bậc (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | ĐĂNG | Xác thực kết nối proxy và trả về IP công cộng/độ trễ | -| `/v1/providers/[provider]/chat/completions` | ĐĂNG | Hoàn thành trò chuyện dành riêng cho mỗi nhà cung cấp với xác thực mô hình | -| `/v1/providers/[provider]/embeddings` | ĐĂNG | Phần nhúng dành riêng cho mỗi nhà cung cấp với xác thực mô hình | -| `/v1/providers/[provider]/images/generations` | ĐĂNG | Tạo hình ảnh chuyên dụng cho mỗi nhà cung cấp với xác thực mô hình | -| `/api/settings/ip-filter` | NHẬN/ĐẶT | Quản lý danh sách chặn/danh sách IP cho phép | -| `/api/settings/thinking-budget` | NHẬN/ĐẶT | Cấu hình ngân sách mã thông báo hợp lý (chuyển qua/tự động/tùy chỉnh/thích ứng) | -| `/api/settings/system-prompt` | NHẬN/ĐẶT | Hệ thống nhắc nhở toàn cầu cho tất cả các yêu cầu | -| `/api/sessions` | NHẬN | Theo dõi và đo lường phiên hoạt động | -| `/api/rate-limits` | NHẬN | Trạng thái giới hạn tỷ lệ cho mỗi tài khoản | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. Các mẫu thiết kế chính +## 5. Key Design Patterns -### 5.1 Dịch Hub-and-Spoke +### 5.1 Hub-and-Spoke Translation -Tất cả các định dạng đều dịch qua **định dạng OpenAI làm trung tâm**. Việc thêm nhà cung cấp mới chỉ yêu cầu viết **một cặp** người dịch (đến/từ OpenAI), chứ không phải N cặp. +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 Mẫu chiến lược thực thi +### 5.2 Executor Strategy Pattern -Mỗi nhà cung cấp có một lớp người thực thi chuyên dụng kế thừa từ `BaseExecutor`. Nhà máy ở `executors/index.ts` chọn đúng nhà máy khi chạy. +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 Hệ thống Plugin tự đăng ký +### 5.3 Self-Registering Plugin System -Mô-đun dịch tự đăng ký khi nhập qua `register()`. Việc thêm người dịch mới chỉ là tạo một tệp và nhập tệp đó. +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 Dự phòng tài khoản với thời gian chờ theo cấp số nhân +### 5.4 Account Fallback with Exponential Backoff -Khi nhà cung cấp trả về 429/401/500, hệ thống có thể chuyển sang tài khoản tiếp theo, áp dụng thời gian hồi chiêu theo cấp số nhân (1 giây → 2 giây → 4 giây → tối đa 2 phút). +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 Chuỗi mô hình kết hợp +### 5.5 Combo Model Chains -Một "combo" nhóm nhiều chuỗi `provider/model`. Nếu lần đầu tiên không thành công, hãy tự động chuyển sang lần tiếp theo. +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 Bản dịch phát trực tuyến có trạng thái +### 5.6 Stateful Streaming Translation -Bản dịch phản hồi duy trì trạng thái trên các khối SSE (theo dõi khối suy nghĩ, tích lũy lệnh gọi công cụ, lập chỉ mục khối nội dung) thông qua cơ chế `initState()`. +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 Bộ đệm an toàn sử dụng +### 5.7 Usage Safety Buffer -Bộ đệm 2000 mã thông báo được thêm vào mức sử dụng được báo cáo để ngăn khách hàng đạt đến giới hạn cửa sổ ngữ cảnh do quá tải từ lời nhắc hệ thống và dịch định dạng. +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. Các định dạng được hỗ trợ +## 6. Supported Formats -| Định dạng | Hướng | Mã định danh | -| ---------------------------- | ------------ | ------------------ | -| Hoàn thành trò chuyện OpenAI | nguồn + đích | `openai` | -| API phản hồi OpenAI | nguồn + đích | `openai-responses` | -| Claude nhân loại | nguồn + đích | `claude` | -| Google Song Tử | nguồn + đích | `gemini` | -| Google Song Tử CLI | chỉ mục tiêu | `gemini-cli` | -| Phản lực hấp dẫn | nguồn + đích | `antigravity` | -| AWS Kiro | chỉ mục tiêu | `kiro` | -| Con trỏ | chỉ mục tiêu | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. Nhà cung cấp được hỗ trợ +## 7. Supported Providers -| Nhà cung cấp | Phương thức xác thực | Người thi hành | Ghi chú chính | -| ------------------------ | ---------------------------- | ---------------- | ------------------------------------------------------- | -| Claude nhân loại | Khóa API hoặc OAuth | Mặc định | Sử dụng tiêu đề `x-api-key` | -| Google Song Tử | Khóa API hoặc OAuth | Mặc định | Sử dụng tiêu đề `x-goog-api-key` | -| Google Song Tử CLI | OAuth | Song TửCLI | Sử dụng điểm cuối `streamGenerateContent` | -| Phản lực hấp dẫn | OAuth | Phản lực hấp dẫn | Dự phòng nhiều URL, phân tích cú pháp thử lại tùy chỉnh | -| OpenAI | Khóa API | Mặc định | Xác thực Bearer tiêu chuẩn | -| Codex | OAuth | Codex | Đưa ra hướng dẫn hệ thống, quản lý tư duy | -| Phi công phụ GitHub | Mã thông báo OAuth + Copilot | Github | Mã thông báo kép, bắt chước tiêu đề VSCode | -| Kiro (AWS) | AWS SSO OIDC hoặc Xã hội | Kiro | Phân tích cú pháp luồng sự kiện nhị phân | -| IDE con trỏ | Xác thực tổng kiểm tra | Con trỏ | Mã hóa Protobuf, tổng kiểm tra SHA-256 | -| Qwen | OAuth | Mặc định | Xác thực chuẩn | -| iFlow | OAuth (Cơ bản + Mang) | Mặc định | Tiêu đề xác thực kép | -| OpenRouter | Khóa API | Mặc định | Xác thực Bearer tiêu chuẩn | -| GLM, Kimi, MiniMax | Khóa API | Mặc định | Tương thích với Claude, sử dụng `x-api-key` | -| `openai-compatible-*` | Khóa API | Mặc định | Động: mọi điểm cuối tương thích với OpenAI | -| `anthropic-compatible-*` | Khóa API | Mặc định | Động: mọi điểm cuối tương thích với Claude | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. Tóm tắt luồng dữ liệu +## 8. Data Flow Summary -### Yêu cầu phát trực tuyến +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### Yêu cầu không phát trực tuyến +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### Luồng bỏ qua (Claude CLI) +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/vi/FEATURES.md b/docs/i18n/vi/FEATURES.md index bcb8fa415c..82cc73b67b 100644 --- a/docs/i18n/vi/FEATURES.md +++ b/docs/i18n/vi/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — Thư viện tính năng bảng điều khiển +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -Hướng dẫn trực quan cho mọi phần của bảng điều khiển OmniRoute. +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 Nhà cung cấp +## 🔌 Providers -Quản lý kết nối của nhà cung cấp AI: Nhà cung cấp OAuth (Claude Code, Codex, Gemini CLI), nhà cung cấp khóa API (Groq, DeepSeek, OpenRouter) và nhà cung cấp miễn phí (iFlow, Qwen, Kiro). +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 Combo +## 🎨 Combos -Tạo các tổ hợp định tuyến mô hình với 6 chiến lược: điền trước, quay vòng, sức mạnh của hai lựa chọn, ngẫu nhiên, ít sử dụng nhất và tối ưu hóa chi phí. Mỗi combo kết hợp nhiều mô hình với tính năng dự phòng tự động. +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 Phân tích +## 📊 Analytics -Phân tích sử dụng toàn diện với mức tiêu thụ mã thông báo, ước tính chi phí, bản đồ nhiệt hoạt động, biểu đồ phân phối hàng tuần và phân tích theo từng nhà cung cấp. +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 Sức khỏe hệ thống +## 🏥 System Health -Giám sát thời gian thực: thời gian hoạt động, bộ nhớ, phiên bản, phần trăm độ trễ (p50/p95/p99), thống kê bộ đệm và trạng thái ngắt mạch của nhà cung cấp. +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 Sân chơi dịch thuật +## 🔧 Translator Playground -Bốn chế độ để gỡ lỗi các bản dịch API: **Playground** (trình chuyển đổi định dạng), **Chat Test** (yêu cầu trực tiếp), **Test Bench** (kiểm tra hàng loạt) và **Live Monitor** (luồng thời gian thực). +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ Cài đặt +## 🎮 Model Playground _(v2.0.9+)_ -Cài đặt chung, lưu trữ hệ thống, quản lý sao lưu (xuất/nhập cơ sở dữ liệu), giao diện (chế độ tối/sáng), bảo mật (bao gồm bảo vệ điểm cuối API và chặn nhà cung cấp tùy chỉnh), định tuyến, khả năng phục hồi và cấu hình nâng cao. +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 Công cụ CLI +## 🔧 CLI Tools -Cấu hình bằng một cú nhấp chuột cho các công cụ mã hóa AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code và AntiGravity. +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 Nhật ký yêu cầu +## 🤖 CLI Agents _(v2.0.11+)_ -Ghi nhật ký yêu cầu theo thời gian thực với tính năng lọc theo nhà cung cấp, kiểu máy, tài khoản và khóa API. Hiển thị mã trạng thái, mức sử dụng mã thông báo, độ trễ và chi tiết phản hồi. +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 Điểm cuối API +## 🌐 API Endpoint -Điểm cuối API hợp nhất của bạn với phân tích khả năng: Hoàn thành trò chuyện, Nhúng, Tạo hình ảnh, Xếp hạng lại, Phiên âm âm thanh và khóa API đã đăng ký. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/vi/TROUBLESHOOTING.md b/docs/i18n/vi/TROUBLESHOOTING.md index b5ed1df555..120092d63c 100644 --- a/docs/i18n/vi/TROUBLESHOOTING.md +++ b/docs/i18n/vi/TROUBLESHOOTING.md @@ -1,87 +1,87 @@ -# Khắc phục sự cố +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -Các vấn đề thường gặp và giải pháp cho OmniRoute. +Common problems and solutions for OmniRoute. --- -## Sửa nhanh +## Quick Fixes -| Vấn đề | Giải pháp | -| ----------------------------------------- | ----------------------------------------------------------------- | -| Đăng nhập lần đầu không hoạt động | Kiểm tra `INITIAL_PASSWORD` trong `.env` (mặc định: `123456`) | -| Bảng điều khiển mở sai cổng | Đặt `PORT=20128` và `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| Không có nhật ký yêu cầu nào dưới `logs/` | Đặt `ENABLE_REQUEST_LOGS=true` | -| EACCES: quyền bị từ chối | Đặt `DATA_DIR=/path/to/writable/dir` để ghi đè `~/.omniroute` | -| Chiến lược định tuyến không tiết kiệm | Cập nhật lên v1.4.11+ (Sửa lược đồ Zod để duy trì cài đặt) | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## Vấn đề về nhà cung cấp +## Provider Issues -### "Mô hình ngôn ngữ không cung cấp thông báo" +### "Language model did not provide messages" -**Nguyên nhân:** Đã hết hạn ngạch nhà cung cấp. +**Cause:** Provider quota exhausted. -**Sửa chữa:** +**Fix:** -1. Kiểm tra trình theo dõi hạn ngạch trên trang tổng quan -2. Sử dụng kết hợp với các tầng dự phòng -3. Chuyển sang cấp rẻ hơn/miễn phí +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### Giới hạn tỷ lệ +### Rate Limiting -**Lý do:** Đã hết hạn mức đăng ký. +**Cause:** Subscription quota exhausted. -**Sửa chữa:** +**Fix:** -- Thêm dự phòng: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Sử dụng GLM/MiniMax làm bản sao lưu giá rẻ +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### Mã thông báo OAuth đã hết hạn +### OAuth Token Expired -OmniRoute tự động làm mới mã thông báo. Nếu vấn đề vẫn tiếp diễn: +OmniRoute auto-refreshes tokens. If issues persist: -1. Bảng điều khiển → Nhà cung cấp → Kết nối lại -2. Xóa và thêm lại kết nối nhà cung cấp +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## Sự cố về đám mây +## Cloud Issues -### Lỗi đồng bộ hóa đám mây +### Cloud Sync Errors -1. Xác minh `BASE_URL` trỏ tới phiên bản đang chạy của bạn (ví dụ: `http://localhost:20128`) -2. Xác minh `CLOUD_URL` trỏ đến điểm cuối đám mây của bạn (ví dụ: `https://omniroute.dev`) -3. Giữ các giá trị `NEXT_PUBLIC_*` được căn chỉnh với các giá trị phía máy chủ +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### Đám mây `stream=false` Trả về 500 +### Cloud `stream=false` Returns 500 -**Triệu chứng:** `Unexpected token 'd'...` trên điểm cuối đám mây đối với các cuộc gọi không phát trực tuyến. +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**Lý do:** Ngược dòng trả về tải trọng SSE trong khi khách hàng mong đợi JSON. +**Cause:** Upstream returns SSE payload while client expects JSON. -**Giải pháp:** Sử dụng `stream=true` cho cuộc gọi trực tiếp qua đám mây. Thời gian chạy cục bộ bao gồm dự phòng SSE→JSON. +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### Cloud cho biết Đã kết nối nhưng "Khóa API không hợp lệ" +### Cloud Says Connected but "Invalid API key" -1. Tạo khóa mới từ bảng điều khiển cục bộ (`/api/keys`) -2. Chạy đồng bộ đám mây: Bật Đám mây → Đồng bộ hóa ngay -3. Khóa cũ/không được đồng bộ hóa vẫn có thể trả về `401` trên đám mây +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Vấn đề về Docker +## Docker Issues -### Công cụ CLI hiển thị chưa được cài đặt +### CLI Tool Shows Not Installed -1. Kiểm tra các trường thời gian chạy: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Đối với chế độ di động: sử dụng mục tiêu hình ảnh `runner-cli` (CLI đi kèm) -3. Đối với chế độ gắn máy chủ: đặt `CLI_EXTRA_PATHS` và gắn thư mục bin máy chủ ở chế độ chỉ đọc -4. Nếu `installed=true` và `runnable=false`: đã tìm thấy nhị phân nhưng kiểm tra tình trạng không thành công +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### Xác thực thời gian chạy nhanh +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -91,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## Vấn đề về chi phí +## Cost Issues -### Chi phí cao +### High Costs -1. Kiểm tra số liệu thống kê sử dụng trong Bảng điều khiển → Mức sử dụng -2. Chuyển model chính sang GLM/MiniMax -3. Sử dụng bậc miễn phí (Gemini CLI, iFlow) cho các tác vụ không quan trọng -4. Đặt ngân sách chi phí cho mỗi khóa API: Bảng điều khiển → Khóa API → Ngân sách +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## Gỡ lỗi +## Debugging -### Kích hoạt nhật ký yêu cầu +### Enable Request Logs -Đặt `ENABLE_REQUEST_LOGS=true` trong tệp `.env` của bạn. Nhật ký xuất hiện trong thư mục `logs/`. +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### Kiểm tra sức khỏe nhà cung cấp +### Check Provider Health ```bash # Health dashboard @@ -118,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### Bộ nhớ thời gian chạy +### Runtime Storage -- Trạng thái chính: `${DATA_DIR}/db.json` (nhà cung cấp, tổ hợp, bí danh, khóa, cài đặt) -- Cách sử dụng: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` -- Nhật ký yêu cầu: `/logs/...` (khi `ENABLE_REQUEST_LOGS=true`) +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## Sự cố ngắt mạch +## Circuit Breaker Issues -### Nhà cung cấp bị kẹt ở trạng thái MỞ +### Provider stuck in OPEN state -Khi cầu dao của nhà cung cấp MỞ, các yêu cầu sẽ bị chặn cho đến khi hết thời gian hồi chiêu. +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**Sửa chữa:** +**Fix:** -1. Đi tới **Bảng điều khiển → Cài đặt → Khả năng phục hồi** -2. Kiểm tra thẻ cầu dao của nhà cung cấp bị ảnh hưởng -3. Nhấp vào **Đặt lại tất cả** để xóa tất cả các bộ ngắt hoặc đợi hết thời gian hồi chiêu -4. Xác minh nhà cung cấp thực sự có sẵn trước khi đặt lại +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### Nhà cung cấp liên tục ngắt cầu dao +### Provider keeps tripping the circuit breaker -Nếu nhà cung cấp liên tục chuyển sang trạng thái MỞ: +If a provider repeatedly enters OPEN state: -1. Kiểm tra **Bảng điều khiển → Sức khỏe → Tình trạng nhà cung cấp** để biết kiểu lỗi -2. Đi tới **Cài đặt → Khả năng phục hồi → Hồ sơ nhà cung cấp** và tăng ngưỡng thất bại -3. Kiểm tra xem nhà cung cấp có thay đổi giới hạn API hay yêu cầu xác thực lại không -4. Xem lại phép đo từ xa về độ trễ - độ trễ cao có thể gây ra lỗi dựa trên thời gian chờ +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## Sự cố phiên âm âm thanh +## Audio Transcription Issues -### Lỗi "Mẫu máy không được hỗ trợ" +### "Unsupported model" error -- Đảm bảo bạn đang sử dụng đúng tiền tố: `deepgram/nova-3` hoặc `assemblyai/best` -- Xác minh nhà cung cấp được kết nối trong **Bảng điều khiển → Nhà cung cấp** +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### Phiên âm trả về trống hoặc không thành công +### Transcription returns empty or fails -- Kiểm tra các định dạng âm thanh được hỗ trợ: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` -- Xác minh kích thước tệp nằm trong giới hạn của nhà cung cấp (thường < 25 MB) -- Kiểm tra tính hợp lệ của khóa API nhà cung cấp trong thẻ nhà cung cấp +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## Gỡ lỗi trình dịch +## Translator Debugging -Sử dụng **Trang tổng quan → Trình dịch** để gỡ lỗi các vấn đề dịch định dạng: +Use **Dashboard → Translator** to debug format translation issues: -| Chế độ | Khi nào nên sử dụng | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------ | -| **Sân chơi** | So sánh các định dạng đầu vào/đầu ra cạnh nhau — dán một yêu cầu không thành công để xem nó dịch như thế nào | -| **Người kiểm tra trò chuyện** | Gửi tin nhắn trực tiếp và kiểm tra toàn bộ tải trọng yêu cầu/phản hồi bao gồm các tiêu đề | -| **Bàn thử nghiệm** | Chạy thử nghiệm hàng loạt trên các kết hợp định dạng để tìm ra bản dịch nào bị lỗi | -| **Màn hình trực tiếp** | Xem luồng yêu cầu theo thời gian thực để nắm bắt các vấn đề dịch thuật không liên tục | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### Các vấn đề định dạng thường gặp +### Common format issues -- **Thẻ tư duy không xuất hiện** — Kiểm tra xem nhà cung cấp mục tiêu có hỗ trợ tư duy và cài đặt ngân sách tư duy hay không -- **Giảm cuộc gọi công cụ** — Một số bản dịch định dạng có thể loại bỏ các trường không được hỗ trợ; xác minh ở chế độ Playground -- **Thiếu lời nhắc hệ thống** — Claude và Gemini xử lý lời nhắc hệ thống theo cách khác nhau; kiểm tra đầu ra bản dịch -- **SDK trả về chuỗi thô thay vì đối tượng** — Đã sửa trong v1.1.0: trình khử trùng phản hồi hiện loại bỏ các trường không chuẩn (`x_groq`, `usage_breakdown`, v.v.) gây ra lỗi xác thực OpenAI SDK Pydantic -- **GLM/ERNIE từ chối vai trò `system`** — Đã sửa trong v1.1.0: bộ chuẩn hóa vai trò tự động hợp nhất các thông báo hệ thống thành thông báo người dùng cho các kiểu máy không tương thích -- **`developer` vai trò không được nhận dạng** — Đã sửa trong v1.1.0: tự động chuyển đổi thành `system` cho các nhà cung cấp không phải OpenAI -- **`json_schema` không hoạt động với Gemini** — Đã sửa trong v1.1.0: `response_format` hiện được chuyển đổi thành `responseMimeType` + `responseSchema` của Gemini +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## Cài đặt khả năng phục hồi +## Resilience Settings -### Giới hạn tỷ lệ tự động không kích hoạt +### Auto rate-limit not triggering -- Giới hạn tỷ lệ tự động chỉ áp dụng cho nhà cung cấp khóa API (không phải OAuth/đăng ký) -- Xác minh **Cài đặt → Khả năng phục hồi → Hồ sơ nhà cung cấp** đã bật giới hạn tỷ lệ tự động -- Kiểm tra xem nhà cung cấp có trả về `429` mã trạng thái hoặc tiêu đề `Retry-After` không +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### Điều chỉnh độ trễ theo cấp số nhân +### Tuning exponential backoff -Hồ sơ nhà cung cấp hỗ trợ các cài đặt này: +Provider profiles support these settings: -- **Độ trễ cơ bản** — Thời gian chờ ban đầu sau lần thất bại đầu tiên (mặc định: 1 giây) -- **Độ trễ tối đa** — Giới hạn thời gian chờ tối đa (mặc định: 30 giây) -- **Hệ số** — Độ trễ tăng lên bao nhiêu cho mỗi lần thất bại liên tiếp (mặc định: 2x) +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### Đàn chống sấm sét +### Anti-thundering herd -Khi nhiều yêu cầu đồng thời gặp phải một nhà cung cấp có tỷ lệ giới hạn, OmniRoute sử dụng mutex + giới hạn tốc độ tự động để tuần tự hóa các yêu cầu và ngăn chặn lỗi xếp tầng. Điều này là tự động đối với các nhà cung cấp khóa API. +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## Vẫn bị kẹt? +## Optional RAG / LLM failure taxonomy (16 problems) -- **Vấn đề về GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Kiến trúc**: Xem [link](ARCHITECTURE.md) để biết chi tiết nội bộ -- **Tham khảo API**: Xem [link](API_REFERENCE.md) để biết tất cả các điểm cuối -- **Bảng điều khiển sức khỏe**: Kiểm tra **Bảng điều khiển → Sức khỏe** để biết trạng thái hệ thống theo thời gian thực -- **Trình dịch**: Sử dụng **Bảng điều khiển → Trình dịch** để gỡ lỗi các vấn đề về định dạng +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/vi/USER_GUIDE.md b/docs/i18n/vi/USER_GUIDE.md index 0fa0303397..5a043224df 100644 --- a/docs/i18n/vi/USER_GUIDE.md +++ b/docs/i18n/vi/USER_GUIDE.md @@ -1,12 +1,12 @@ -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +# User Guide -#Hướng dẫn sử dụng +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -Hướng dẫn đầy đủ về cách định cấu hình nhà cung cấp, tạo tổ hợp, tích hợp công cụ CLI và triển khai OmniRoute. +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## Mục lục +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ Hướng dẫn đầy đủ về cách định cấu hình nhà cung cấp, tạ --- -## 💰 Sơ lược về giá +## 💰 Pricing at a Glance -| Bậc | Nhà cung cấp | Chi phí | Đặt lại hạn ngạch | Tốt nhất cho | -| --------------- | ------------------- | ---------------------------- | --------------------- | -------------------------- | -| **💳 ĐĂNG KÝ** | Mã Claude (Pro) | $20/tháng | 5h + hàng tuần | Đã đăng ký | -| | Codex (Plus/Pro) | $20-200/tháng | 5h + hàng tuần | Người dùng OpenAI | -| | Song Tử CLI | **MIỄN PHÍ** | 180K/tháng + 1K/ngày | Mọi người! | -| | Phi công phụ GitHub | $10-19/tháng | Hàng tháng | Người dùng GitHub | -| **🔑 KHÓA API** | DeepSeek | Trả tiền cho mỗi lần sử dụng | Không có | Lý luận giá rẻ | -| | Groq | Trả tiền cho mỗi lần sử dụng | Không có | Suy luận cực nhanh | -| | xAI (Grok) | Trả tiền cho mỗi lần sử dụng | Không có | Lý luận Grok 4 | -| | Mistral | Trả tiền cho mỗi lần sử dụng | Không có | Các mô hình do EU đăng cai | -| | Lúng túng | Trả tiền cho mỗi lần sử dụng | Không có | Tăng cường tìm kiếm | -| | Cùng AI | Trả tiền cho mỗi lần sử dụng | Không có | Mô hình nguồn mở | -| | Pháo hoa AI | Trả tiền cho mỗi lần sử dụng | Không có | Hình ảnh FLUX nhanh | -| | Não | Trả tiền cho mỗi lần sử dụng | Không có | Tốc độ quy mô wafer | -| | Kết hợp | Trả tiền cho mỗi lần sử dụng | Không có | Lệnh R+ RAG | -| | NVIDIA NIM | Trả tiền cho mỗi lần sử dụng | Không có | Mô hình doanh nghiệp | -| **💰 RẺ** | GLM-4.7 | 0,6 USD/1 triệu USD | 10 giờ sáng hàng ngày | Dự phòng ngân sách | -| | MiniMax M2.1 | 0,2 USD/1 triệu USD | lăn 5 giờ | Lựa chọn rẻ nhất | -| | Kimi K2 | $9/tháng căn hộ | 10 triệu token/tháng | Chi phí dự đoán | -| **🆓 MIỄN PHÍ** | iFlow | $0 | Không giới hạn | 8 mẫu miễn phí | -| | Qwen | $0 | Không giới hạn | 3 mẫu miễn phí | -| | Kiro | $0 | Không giới hạn | Claude miễn phí | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡 Mẹo chuyên nghiệp:** Bắt đầu với Gemini CLI (180K miễn phí/tháng) + combo iFlow (miễn phí không giới hạn) = chi phí $0! +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 Trường hợp sử dụng +## 🎯 Use Cases -### Trường hợp 1: "Tôi có đăng ký Claude Pro" +### Case 1: "I have Claude Pro subscription" -**Vấn đề:** Hạn ngạch hết hạn không được sử dụng, giới hạn tốc độ trong quá trình mã hóa nặng +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### Trường hợp 2: "Tôi muốn chi phí bằng 0" +### Case 2: "I want zero cost" -**Vấn đề:** Không đủ khả năng đăng ký, cần mã hóa AI đáng tin cậy +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### Trường hợp 3: "Tôi cần code 24/7, không bị gián đoạn" +### Case 3: "I need 24/7 coding, no interruptions" -**Vấn đề:** Thời hạn, không đủ khả năng cho thời gian ngừng hoạt động +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### Trường hợp 4: "Tôi muốn AI MIỄN PHÍ trong OpenClaw" +### Case 4: "I want FREE AI in OpenClaw" -**Vấn đề:** Cần trợ lý AI trong ứng dụng nhắn tin, hoàn toàn miễn phí +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 Thiết lập nhà cung cấp +## 📖 Provider Setup -### 🔐 Nhà cung cấp đăng ký +### 🔐 Subscription Providers -#### Mã Claude (Pro/Max) +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,7 +126,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Mẹo chuyên nghiệp:** Sử dụng Opus cho các tác vụ phức tạp, Sonnet cho tốc độ. OmniRoute theo dõi hạn ngạch cho mỗi mô hình! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! #### OpenAI Codex (Plus/Pro) @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI (MIỄN PHÍ 180K/tháng!) +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,7 +152,7 @@ Models: gc/gemini-2.5-pro ``` -**Giá trị tốt nhất:** Cấp miễn phí rất lớn! Sử dụng điều này trước các bậc trả phí. +**Best Value:** Huge free tier! Use this before paid tiers. #### GitHub Copilot @@ -167,33 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 Nhà cung cấp giá rẻ +### 💰 Cheap Providers -#### GLM-4.7 (Đặt lại hàng ngày, 0,6 USD/1 triệu USD) +#### GLM-4.7 (Daily reset, $0.6/1M) -1. Đăng ký: [Zhipu AI](https://open.bigmodel.cn/) -2. Nhận khóa API từ Gói mã hóa -3. Bảng điều khiển → Thêm khóa API: Nhà cung cấp: `glm`, Khóa API: `your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**Sử dụng:** `glm/glm-4.7` — **Mẹo chuyên nghiệp:** Gói mã hóa cung cấp hạn ngạch 3× với chi phí 1/7! Đặt lại vào 10:00 sáng hàng ngày. +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1 (đặt lại 5 giờ, 0,20 USD/1 triệu) +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. Đăng ký: [MiniMax](https://www.minimax.io/) -2. Nhận khóa API → Bảng điều khiển → Thêm khóa API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**Sử dụng:** `minimax/MiniMax-M2.1` — **Mẹo chuyên nghiệp:** Tùy chọn rẻ nhất cho bối cảnh dài (1 triệu mã thông báo)! +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2 ($9/tháng cố định) +#### Kimi K2 ($9/month flat) -1. Đăng ký: [Moonshot AI](https://platform.moonshot.ai/) -2. Nhận khóa API → Bảng điều khiển → Thêm khóa API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**Sử dụng:** `kimi/kimi-latest` — **Mẹo chuyên nghiệp:** Đã sửa lỗi 9 USD/tháng cho 10 triệu mã thông báo = 0,90 USD/1 triệu chi phí hiệu quả! +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 Nhà cung cấp MIỄN PHÍ +### 🆓 FREE Providers -#### iFlow (8 mẫu MIỄN PHÍ) +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -201,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen (3 mẫu MIỄN PHÍ) +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -209,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro (Claude MIỄN PHÍ) +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -219,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 Combo +## 🎨 Combos -### Ví dụ 1: Tối đa hóa đăng ký → Sao lưu giá rẻ +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -235,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### Ví dụ 2: Chỉ miễn phí (Không mất phí) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -249,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 Tích hợp CLI +## 🔧 CLI Integration -### IDE con trỏ +### Cursor IDE ``` Settings → Models → Advanced: @@ -260,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Mã Claude +### Claude Code -Chỉnh sửa `~/.claude/config.json`: +Edit `~/.claude/config.json`: ```json { @@ -281,7 +281,7 @@ codex "your prompt" ### OpenClaw -Chỉnh sửa `~/.openclaw/openclaw.json`: +Edit `~/.openclaw/openclaw.json`: ```json { @@ -303,9 +303,9 @@ Chỉnh sửa `~/.openclaw/openclaw.json`: } ``` -**Hoặc sử dụng Bảng điều khiển:** Công cụ CLI → OpenClaw → Tự động cấu hình +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### Cline / Tiếp tục / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -316,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 Triển khai +## 🚀 Deployment -### Triển khai VPS +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -337,6 +356,43 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + ### Docker ```bash @@ -347,51 +403,54 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -Để biết chế độ tích hợp máy chủ với các tệp nhị phân CLI, hãy xem phần Docker trong tài liệu chính. +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### Biến môi trường +### Environment Variables -| Biến | Mặc định | Mô tả | -| --------------------- | ------------------------------------ | ---------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Bí mật ký kết JWT (**thay đổi trong sản xuất**) | -| `INITIAL_PASSWORD` | `123456` | Mật khẩu đăng nhập lần đầu | -| `DATA_DIR` | `~/.omniroute` | Thư mục dữ liệu (db, cách sử dụng, nhật ký) | -| `PORT` | mặc định khung | Cổng dịch vụ (`20128` trong ví dụ) | -| `HOSTNAME` | mặc định khung | Máy chủ liên kết (Docker mặc định là `0.0.0.0`) | -| `NODE_ENV` | mặc định thời gian chạy | Đặt `production` để triển khai | -| `BASE_URL` | `http://localhost:20128` | URL cơ sở nội bộ phía máy chủ | -| `CLOUD_URL` | `https://omniroute.dev` | URL cơ sở điểm cuối đồng bộ hóa đám mây | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Bí mật HMAC cho các khóa API được tạo | -| `REQUIRE_API_KEY` | `false` | Thực thi khóa API Bearer trên `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Bật nhật ký yêu cầu/phản hồi | -| `AUTH_COOKIE_SECURE` | `false` | Buộc `Secure` cookie xác thực (đằng sau proxy ngược HTTPS) | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -Để biết tham chiếu đầy đủ về biến môi trường, hãy xem [README](../README.md). +For the full environment variable reference, see the [README](../README.md). --- -## 📊 Mẫu có sẵn +## 📊 Available Models
-Xem tất cả các mẫu có sẵn +View all available models -**Mã Claude (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — MIỄN PHÍ: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` **GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — 0,6 USD/1 triệu: `glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — 0,2 USD/1 triệu: `minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — MIỄN PHÍ: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — MIỄN PHÍ: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — MIỄN PHÍ: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` **DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` @@ -401,13 +460,13 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat **Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**Bối rối (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**Cùng AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**Pháo hoa AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Não (`cerebras/`)**: `cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` **Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` @@ -417,11 +476,11 @@ docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-dat --- -## 🧩 Tính năng nâng cao +## 🧩 Advanced Features -### Mẫu tùy chỉnh +### Custom Models -Thêm bất kỳ ID mẫu nào vào bất kỳ nhà cung cấp nào mà không cần chờ cập nhật ứng dụng: +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -433,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -Hoặc sử dụng Trang tổng quan: **Nhà cung cấp → [Nhà cung cấp] → Mô hình tùy chỉnh**. +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### Tuyến đường dành riêng cho nhà cung cấp +### Dedicated Provider Routes -Định tuyến các yêu cầu trực tiếp đến một nhà cung cấp cụ thể với xác thực mô hình: +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -445,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -Tiền tố nhà cung cấp được tự động thêm vào nếu thiếu. Các mô hình không khớp trả về `400`. +The provider prefix is auto-added if missing. Mismatched models return `400`. -### Cấu hình proxy mạng +### Network Proxy Configuration ```bash # Set global proxy @@ -463,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**Ưu tiên:** Dành riêng cho khóa → Dành riêng cho tổ hợp → Dành riêng cho nhà cung cấp → Toàn cầu → Môi trường. +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### API danh mục mẫu +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -Trả về các mô hình được nhóm theo nhà cung cấp với các loại (`chat`, `embedding`, `image`). +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### Đồng bộ đám mây +### Cloud Sync -- Đồng bộ hóa nhà cung cấp, combo và cài đặt trên các thiết bị -- Đồng bộ hóa nền tự động với thời gian chờ + không nhanh -- Ưu tiên phía máy chủ `BASE_URL`/`CLOUD_URL` phía máy chủ trong sản xuất +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence (Giai đoạn 9) +### LLM Gateway Intelligence (Phase 9) -- **Bộ nhớ đệm ngữ nghĩa** — Tự động lưu vào bộ nhớ đệm khi không phát trực tuyến, phản hồi nhiệt độ=0 (bỏ qua bằng `X-OmniRoute-No-Cache: true`) -- **Yêu cầu Idempotency** — Loại bỏ các yêu cầu trùng lặp trong vòng 5 giây thông qua tiêu đề `Idempotency-Key` hoặc `X-Request-Id` -- **Theo dõi tiến trình** — Chọn tham gia các sự kiện SSE `event: progress` qua tiêu đề `X-OmniRoute-Progress: true` +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### Sân chơi dịch thuật +### Translator Playground -Truy cập qua **Bảng điều khiển → Trình dịch**. Gỡ lỗi và trực quan hóa cách OmniRoute dịch các yêu cầu API giữa các nhà cung cấp. +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| Chế độ | Mục đích | -| ----------------------------- | ---------------------------------------------------------------------------------------------- | -| **Sân chơi** | Chọn định dạng nguồn/đích, dán yêu cầu và xem bản dịch ngay lập tức | -| **Người kiểm tra trò chuyện** | Gửi tin nhắn trò chuyện trực tiếp qua proxy và kiểm tra toàn bộ chu trình yêu cầu/phản hồi | -| **Bàn thử nghiệm** | Chạy thử nghiệm hàng loạt trên nhiều kết hợp định dạng để xác minh tính chính xác của bản dịch | -| **Màn hình trực tiếp** | Xem các bản dịch theo thời gian thực khi các yêu cầu chuyển qua proxy | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**Trường hợp sử dụng:** +**Use cases:** -- Gỡ lỗi tại sao kết hợp khách hàng/nhà cung cấp cụ thể không thành công -- Xác minh rằng thẻ tư duy, lệnh gọi công cụ và lời nhắc hệ thống được dịch chính xác -- So sánh sự khác biệt về định dạng giữa các định dạng API OpenAI, Claude, Gemini và Responses +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### Chiến lược định tuyến +### Routing Strategies -Định cấu hình qua **Bảng điều khiển → Cài đặt → Định tuyến**. +Configure via **Dashboard → Settings → Routing**. -| Chiến lược | Mô tả | -| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| **Điền đầu tiên** | Sử dụng các tài khoản theo thứ tự ưu tiên - tài khoản chính xử lý tất cả các yêu cầu cho đến khi không có sẵn | -| **Vòng tròn** | Xoay vòng qua tất cả các tài khoản với giới hạn cố định có thể định cấu hình (mặc định: 3 cuộc gọi cho mỗi tài khoản) | -| **P2C (Sức mạnh của hai lựa chọn)** | Chọn 2 tài khoản ngẫu nhiên và hướng đến tài khoản lành mạnh hơn — cân bằng tải trọng với nhận thức về sức khỏe | -| **Ngẫu nhiên** | Chọn ngẫu nhiên một tài khoản cho mỗi yêu cầu bằng cách sử dụng tính năng ngẫu nhiên Fisher-Yates | -| **Ít sử dụng nhất** | Định tuyến tới tài khoản có dấu thời gian `lastUsedAt` cũ nhất, phân bổ lưu lượng truy cập đồng đều | -| **Tối ưu hóa chi phí** | Định tuyến đến tài khoản có giá trị ưu tiên thấp nhất, tối ưu hóa cho nhà cung cấp có chi phí thấp nhất | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### Bí danh mô hình ký tự đại diện +#### Wildcard Model Aliases -Tạo các mẫu ký tự đại diện để ánh xạ lại tên mô hình: +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -Hỗ trợ ký tự đại diện `*` (bất kỳ ký tự nào) và `?` (ký tự đơn). +Wildcards support `*` (any characters) and `?` (single character). -#### Chuỗi dự phòng +#### Fallback Chains -Xác định chuỗi dự phòng toàn cầu áp dụng cho tất cả các yêu cầu: +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -543,46 +602,46 @@ Chain: production-fallback --- -### Khả năng phục hồi & Bộ ngắt mạch +### Resilience & Circuit Breakers -Định cấu hình qua **Bảng điều khiển → Cài đặt → Khả năng phục hồi**. +Configure via **Dashboard → Settings → Resilience**. -OmniRoute triển khai khả năng phục hồi cấp nhà cung cấp với bốn thành phần: +OmniRoute implements provider-level resilience with four components: -1. **Hồ sơ nhà cung cấp** — Cấu hình cho mỗi nhà cung cấp cho: - - Ngưỡng thất bại (có bao nhiêu lần thất bại trước khi mở) - - Thời gian hồi chiêu - - Độ nhạy phát hiện giới hạn tốc độ - - Thông số backoff theo cấp số nhân +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **Giới hạn tỷ lệ có thể chỉnh sửa** — Giá trị mặc định ở cấp hệ thống có thể định cấu hình trong trang tổng quan: - - **Số yêu cầu mỗi phút (RPM)** — Số yêu cầu tối đa mỗi phút cho mỗi tài khoản - - **Thời gian tối thiểu giữa các yêu cầu** — Khoảng cách tối thiểu tính bằng mili giây giữa các yêu cầu - - **Số yêu cầu đồng thời tối đa** — Số yêu cầu đồng thời tối đa cho mỗi tài khoản - - Nhấp vào **Chỉnh sửa** để sửa đổi, sau đó nhấp vào **Lưu** hoặc **Hủy**. Các giá trị vẫn tồn tại thông qua API khả năng phục hồi. +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **Bộ ngắt mạch** — Theo dõi lỗi của mỗi nhà cung cấp và tự động mở mạch khi đạt đến ngưỡng: - - **ĐÓNG** (Khỏe mạnh) — Yêu cầu diễn ra bình thường - - **OPEN** — Nhà cung cấp bị chặn tạm thời sau nhiều lần thất bại - - **HALF_OPEN** — Kiểm tra xem nhà cung cấp đã phục hồi chưa +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **Chính sách & Mã định danh bị khóa** — Hiển thị trạng thái cầu dao và mã định danh bị khóa với khả năng buộc mở khóa. +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **Tự động phát hiện giới hạn tốc độ** — Giám sát các tiêu đề `429` và `Retry-After` để chủ động tránh chạm tới giới hạn tốc độ của nhà cung cấp. +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**Mẹo chuyên nghiệp:** Sử dụng nút **Đặt lại tất cả** để xóa tất cả cầu dao và thời gian hồi chiêu khi nhà cung cấp khôi phục sau khi ngừng hoạt động. +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### Xuất/Nhập cơ sở dữ liệu +### Database Export / Import -Quản lý sao lưu cơ sở dữ liệu trong **Bảng điều khiển → Cài đặt → Hệ thống & Bộ lưu trữ**. +Manage database backups in **Dashboard → Settings → System & Storage**. -| Hành động | Mô tả | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Xuất cơ sở dữ liệu** | Tải xuống cơ sở dữ liệu SQLite hiện tại dưới dạng tệp `.sqlite` | -| **Xuất tất cả (.tar.gz)** | Tải xuống kho lưu trữ sao lưu đầy đủ bao gồm: cơ sở dữ liệu, cài đặt, tổ hợp, kết nối nhà cung cấp (không có thông tin xác thực), siêu dữ liệu khóa API | -| **Nhập cơ sở dữ liệu** | Tải tệp `.sqlite` lên để thay thế cơ sở dữ liệu hiện tại. Bản sao lưu trước khi nhập được tự động tạo | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -596,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**Xác thực nhập:** Tệp đã nhập được xác thực về tính toàn vẹn (kiểm tra pragma SQLite), các bảng bắt buộc (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) và kích thước (tối đa 100MB). +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**Trường hợp sử dụng:** +**Use Cases:** -- Di chuyển OmniRoute giữa các máy -- Tạo bản sao lưu bên ngoài để khắc phục thảm họa -- Chia sẻ cấu hình giữa các thành viên trong nhóm (xuất tất cả → chia sẻ kho lưu trữ) +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### Bảng điều khiển cài đặt +### Settings Dashboard -Trang cài đặt được tổ chức thành 5 tab để dễ dàng điều hướng: +The settings page is organized into 5 tabs for easy navigation: -| Tab | Nội dung | -| --------------------- | ------------------------------------------------------------------------------------------------------------- | -| **An ninh** | Cài đặt đăng nhập/mật khẩu, Kiểm soát truy cập IP, xác thực API cho `/models` và Chặn nhà cung cấp | -| **Định tuyến** | Chiến lược định tuyến toàn cầu (6 tùy chọn), bí danh mô hình ký tự đại diện, chuỗi dự phòng, mặc định kết hợp | -| **Khả năng phục hồi** | Hồ sơ nhà cung cấp, giới hạn tỷ lệ có thể chỉnh sửa, trạng thái ngắt mạch, chính sách và số nhận dạng bị khóa | -| **AI** | Suy nghĩ về cấu hình ngân sách, tiêm nhắc hệ thống toàn cầu, thống kê bộ nhớ đệm nhanh chóng | -| **Nâng cao** | Cấu hình proxy toàn cầu (HTTP/SOCKS5) | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### Quản lý chi phí & ngân sách +### Costs & Budget Management -Truy cập qua **Bảng điều khiển → Chi phí**. +Access via **Dashboard → Costs**. -| Tab | Mục đích | -| ------------- | --------------------------------------------------------------------------------------------------------------- | -| **Ngân sách** | Đặt giới hạn chi tiêu cho mỗi khóa API với ngân sách hàng ngày/hàng tuần/hàng tháng và theo dõi thời gian thực | -| **Giá** | Xem và chỉnh sửa các mục định giá mô hình — chi phí cho mỗi 1K mã thông báo đầu vào/đầu ra cho mỗi nhà cung cấp | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -639,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**Theo dõi chi phí:** Mọi yêu cầu đều ghi lại việc sử dụng mã thông báo và tính toán chi phí bằng bảng giá. Xem thông tin chi tiết trong **Trang tổng quan → Mức sử dụng** theo nhà cung cấp, kiểu máy và khóa API. +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### Phiên âm âm thanh +### Audio Transcription -OmniRoute hỗ trợ sao chép âm thanh thông qua điểm cuối tương thích với OpenAI: +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -659,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -Các nhà cung cấp hiện có: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -Các định dạng âm thanh được hỗ trợ: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### Chiến lược cân bằng kết hợp +### Combo Balancing Strategies -Định cấu hình cân bằng trên mỗi kết hợp trong **Bảng điều khiển → Tổ hợp → Tạo/Chỉnh sửa → Chiến lược**. +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| Chiến lược | Mô tả | -| ------------------------ | --------------------------------------------------------------------------- | -| **Vòng tròn** | Xoay qua các mô hình một cách tuần tự | -| **Ưu tiên** | Luôn thử mẫu đầu tiên; chỉ quay lại khi có lỗi | -| **Ngẫu nhiên** | Chọn một mô hình ngẫu nhiên từ combo cho mỗi yêu cầu | -| **Có trọng số** | Các tuyến đường tương ứng dựa trên trọng số được chỉ định cho mỗi mô hình | -| **Ít được sử dụng nhất** | Định tuyến đến mô hình có ít yêu cầu gần đây nhất (sử dụng số liệu kết hợp) | -| **Tối ưu hóa chi phí** | Hướng đến mô hình có sẵn rẻ nhất (sử dụng bảng giá) | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -Mặc định kết hợp chung có thể được đặt trong **Bảng điều khiển → Cài đặt → Định tuyến → Mặc định kết hợp**. +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### Bảng thông tin sức khỏe +### Health Dashboard -Truy cập qua **Bảng điều khiển → Sức khỏe**. Tổng quan về tình trạng hệ thống theo thời gian thực với 6 thẻ: +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| Thẻ | Nó hiển thị những gì | -| ----------------------------- | ------------------------------------------------------------------------------------- | -| **Trạng thái hệ thống** | Thời gian hoạt động, phiên bản, mức sử dụng bộ nhớ, thư mục dữ liệu | -| **Sức khỏe của nhà cung cấp** | Trạng thái ngắt mạch của mỗi nhà cung cấp (Đóng/Mở/Nửa mở) | -| **Giới hạn tỷ lệ** | Thời gian hồi chiêu giới hạn tốc độ kích hoạt cho mỗi tài khoản với thời gian còn lại | -| **Khóa hoạt động** | Nhà cung cấp bị chặn tạm thời bởi chính sách khóa | -| **Bộ nhớ đệm chữ ký** | Số liệu thống kê bộ đệm chống trùng lặp (khóa hoạt động, tỷ lệ truy cập) | -| **Từ xa độ trễ** | tổng hợp độ trễ p50/p95/p99 cho mỗi nhà cung cấp | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**Mẹo chuyên nghiệp:** Trang Sức khỏe tự động làm mới sau mỗi 10 giây. Sử dụng thẻ ngắt mạch để xác định nhà cung cấp nào đang gặp sự cố. +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/zh-CN/API_REFERENCE.md b/docs/i18n/zh-CN/API_REFERENCE.md index 9c6bef469c..b795722c11 100644 --- a/docs/i18n/zh-CN/API_REFERENCE.md +++ b/docs/i18n/zh-CN/API_REFERENCE.md @@ -1,12 +1,12 @@ -# API 参考 +# API Reference -🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) +🌐 **Languages:** 🇺🇸 [English](API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](i18n/es/API_REFERENCE.md) | 🇫🇷 [Français](i18n/fr/API_REFERENCE.md) | 🇮🇹 [Italiano](i18n/it/API_REFERENCE.md) | 🇷🇺 [Русский](i18n/ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](i18n/de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](i18n/in/API_REFERENCE.md) | 🇹🇭 [ไทย](i18n/th/API_REFERENCE.md) | 🇺🇦 [Українська](i18n/uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](i18n/ar/API_REFERENCE.md) | 🇯🇵 [日本語](i18n/ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/API_REFERENCE.md) | 🇧🇬 [Български](i18n/bg/API_REFERENCE.md) | 🇩🇰 [Dansk](i18n/da/API_REFERENCE.md) | 🇫🇮 [Suomi](i18n/fi/API_REFERENCE.md) | 🇮🇱 [עברית](i18n/he/API_REFERENCE.md) | 🇭🇺 [Magyar](i18n/hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | 🇰🇷 [한국어](i18n/ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](i18n/nl/API_REFERENCE.md) | 🇳🇴 [Norsk](i18n/no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/API_REFERENCE.md) | 🇷🇴 [Română](i18n/ro/API_REFERENCE.md) | 🇵🇱 [Polski](i18n/pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](i18n/sk/API_REFERENCE.md) | 🇸🇪 [Svenska](i18n/sv/API_REFERENCE.md) | 🇵🇭 [Filipino](i18n/phi/API_REFERENCE.md) -所有 OmniRoute API 端点的完整参考。 +Complete reference for all OmniRoute API endpoints. --- -## 目录 +## Table of Contents - [Chat Completions](#chat-completions) - [Embeddings](#embeddings) @@ -20,7 +20,7 @@ --- -## 聊天完成 +## Chat Completions ```bash POST /v1/chat/completions @@ -36,21 +36,21 @@ Content-Type: application/json } ``` -### 自定义标头 +### Custom Headers -| 标题 | 方向 | 描述 | -| ------------------------ | ---- | ----------------------------- | -| `X-OmniRoute-No-Cache` | 请求 | 设置为 `true` 以绕过缓存 | -| `X-OmniRoute-Progress` | 请求 | 对于进度事件设置为 `true` | -| `Idempotency-Key` | 请求 | Dedup 密钥（5 秒窗口） | -| `X-Request-Id` | 请求 | 替代重复数据删除密钥 | -| `X-OmniRoute-Cache` | 回应 | `HIT` 或 `MISS`（非流式传输） | -| `X-OmniRoute-Idempotent` | 回应 | `true` 如果已进行重复数据删除 | -| `X-OmniRoute-Progress` | 回应 | `enabled` 如果进度跟踪开启 | +| Header | Direction | Description | +| ------------------------ | --------- | --------------------------------- | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `Idempotency-Key` | Request | Dedup key (5s window) | +| `X-Request-Id` | Request | Alternative dedup key | +| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated | +| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on | --- -## 嵌入 +## Embeddings ```bash POST /v1/embeddings @@ -63,7 +63,7 @@ Content-Type: application/json } ``` -可用的提供商：Nebius、OpenAI、Mistral、Together AI、Fireworks、NVIDIA。 +Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. ```bash # List all embedding models @@ -72,7 +72,7 @@ GET /v1/embeddings --- -## 图像生成 +## Image Generation ```bash POST /v1/images/generations @@ -86,7 +86,7 @@ Content-Type: application/json } ``` -可用的提供商：OpenAI (DALL-E)、xAI (Grok Image)、Together AI (FLUX)、Fireworks AI。 +Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. ```bash # List all image models @@ -95,7 +95,7 @@ GET /v1/images/generations --- -## 列出型号 +## List Models ```bash GET /v1/models @@ -106,22 +106,22 @@ Authorization: Bearer your-api-key --- -## 兼容性端点 +## Compatibility Endpoints -|方法|路径|格式| -| ------ | ------------------------ | | ---------------------- | -|发布 | `/v1/chat/completions` |开放人工智能 | -|发布 | `/v1/messages` |人择 | -|发布 | `/v1/responses` | OpenAI 回应 | -|发布 | `/v1/embeddings` |开放人工智能 | -|发布 | `/v1/images/generations` |开放人工智能 | -|获取 | `/v1/models` |开放人工智能 | -|发布 | `/v1/messages/count_tokens` |人择 | -|获取 | `/v1beta/models` |双子座| -|发布 | `/v1beta/models/{...path}` |双子座生成内容 | -|发布 | `/v1/api/chat` |奥拉玛 | +| Method | Path | Format | +| ------ | --------------------------- | ---------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Anthropic | +| POST | `/v1/responses` | OpenAI Responses | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Anthropic | +| GET | `/v1beta/models` | Gemini | +| POST | `/v1beta/models/{...path}` | Gemini generateContent | +| POST | `/v1/api/chat` | Ollama | -### 专用提供商路线 +### Dedicated Provider Routes ```bash POST /v1/providers/{provider}/chat/completions @@ -129,11 +129,11 @@ POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` -如果缺少提供商前缀，则会自动添加。不匹配的模型返回 `400`。 +The provider prefix is auto-added if missing. Mismatched models return `400`. --- -## 语义缓存 +## Semantic Cache ```bash # Get cache stats @@ -143,7 +143,7 @@ GET /api/cache DELETE /api/cache ``` -响应示例： +Response example: ```json { @@ -162,154 +162,164 @@ DELETE /api/cache --- -## 仪表板和管理 +## Dashboard & Management -### 身份验证 +### Authentication -| 端点 | 方法 | 描述 | -| ----------------------------- | --------- | ------------ | -| `/api/auth/login` | 发布 | 登录 | -| `/api/auth/logout` | 发布 | 退出 | -| `/api/settings/require-login` | 获取/放置 | 切换需要登录 | +| Endpoint | Method | Description | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | Logout | +| `/api/settings/require-login` | GET/PUT | Toggle login required | -### 提供商管理 +### Provider Management -| 端点 | 方法 | 描述 | -| ---------------------------- | -------------- | --------------- | -| `/api/providers` | 获取/发布 | 列出/创建提供商 | -| `/api/providers/[id]` | 获取/放置/删除 | 管理提供商 | -| `/api/providers/[id]/test` | 发布 | 测试提供商连接 | -| `/api/providers/[id]/models` | 获取 | 列出供应商型号 | -| `/api/providers/validate` | 发布 | 验证提供商配置 | -| `/api/provider-nodes*` | 各种 | 提供商节点管理 | -| `/api/provider-models` | 获取/发布/删除 | 定制型号 | +| Endpoint | Method | Description | +| ---------------------------- | --------------- | ------------------------ | +| `/api/providers` | GET/POST | List / create providers | +| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider | +| `/api/providers/[id]/test` | POST | Test provider connection | +| `/api/providers/[id]/models` | GET | List provider models | +| `/api/providers/validate` | POST | Validate provider config | +| `/api/provider-nodes*` | Various | Provider node management | +| `/api/provider-models` | GET/POST/DELETE | Custom models | -### OAuth 流程 +### OAuth Flows -| 端点 | 方法 | 描述 | -| -------------------------------- | ---- | -------------------- | -| `/api/oauth/[provider]/[action]` | 各种 | 特定于提供商的 OAuth | +| Endpoint | Method | Description | +| -------------------------------- | ------- | ----------------------- | +| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth | -### 路由和配置 +### Routing & Config -| 端点 | 方法 | 描述 | -| --------------------- | --------- | --------------------------- | -| `/api/models/alias` | 获取/发布 | 模型别名 | -| `/api/models/catalog` | 获取 | 按提供商+类型列出的所有型号 | -| `/api/combos*` | 各种 | 组合管理 | -| `/api/keys*` | 各种 | API 密钥管理 | -| `/api/pricing` | 获取 | 型号定价 | +| Endpoint | Method | Description | +| --------------------- | -------- | ----------------------------- | +| `/api/models/alias` | GET/POST | Model aliases | +| `/api/models/catalog` | GET | All models by provider + type | +| `/api/combos*` | Various | Combo management | +| `/api/keys*` | Various | API key management | +| `/api/pricing` | GET | Model pricing | -### 使用与分析 +### Usage & Analytics -|端点 |方法|描述 | -| ------------------------ | | ------ | -------------------- | -| `/api/usage/history` |获取 |使用历史 | -| `/api/usage/logs` |获取 |使用日志 | -| `/api/usage/request-logs` |获取 |请求级日志 | -| `/api/usage/[connectionId]` |获取 |每个连接的使用情况 | +| Endpoint | Method | Description | +| --------------------------- | ------ | -------------------- | +| `/api/usage/history` | GET | Usage history | +| `/api/usage/logs` | GET | Usage logs | +| `/api/usage/request-logs` | GET | Request-level logs | +| `/api/usage/[connectionId]` | GET | Per-connection usage | -### 设置 +### Settings -| 端点 | 方法 | 描述 | -| ------------------------------- | --------- | -------------------- | -| `/api/settings` | 获取/放置 | 常规设置 | -| `/api/settings/proxy` | 获取/放置 | 网络代理配置 | -| `/api/settings/proxy/test` | 发布 | 测试代理连接 | -| `/api/settings/ip-filter` | 获取/放置 | IP 允许列表/阻止列表 | -| `/api/settings/thinking-budget` | 获取/放置 | 推理代币预算 | -| `/api/settings/system-prompt` | 获取/放置 | 全局系统提示 | +| Endpoint | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | -### 监控 +### Monitoring -| 端点 | 方法 | 描述 | -| ------------------------ | --------- | ------------------ | -| `/api/sessions` | 获取 | 活动会话跟踪 | -| `/api/rate-limits` | 获取 | 每个帐户的费率限制 | -| `/api/monitoring/health` | 获取 | 健康检查 | -| `/api/cache` | 获取/删除 | 缓存统计/清除 | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ----------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check | +| `/api/cache` | GET/DELETE | Cache stats / clear | -### 备份和导出/导入 +### Backup & Export/Import -|端点 |方法|描述 | -| ------------------------ | | ------ | --------------------------------------- | -| `/api/db-backups` |获取 |列出可用备份 | -| `/api/db-backups` |放置 |创建手动备份 | -| `/api/db-backups` |发布 |从特定备份恢复| -| `/api/db-backups/export` |获取 |将数据库下载为 .sqlite 文件 | -| `/api/db-backups/import` |发布 |上传.sqlite 文件来替换数据库 | -| `/api/db-backups/exportAll` |获取 |下载完整备份为 .tar.gz 存档 | +| Endpoint | Method | Description | +| --------------------------- | ------ | --------------------------------------- | +| `/api/db-backups` | GET | List available backups | +| `/api/db-backups` | PUT | Create a manual backup | +| `/api/db-backups` | POST | Restore from a specific backup | +| `/api/db-backups/export` | GET | Download database as .sqlite file | +| `/api/db-backups/import` | POST | Upload .sqlite file to replace database | +| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive | -### 云同步 +### Cloud Sync -| 端点 | 方法 | 描述 | -| ---------------------- | ---- | ---------- | -| `/api/sync/cloud` | 各种 | 云同步操作 | -| `/api/sync/initialize` | 发布 | 初始化同步 | -| `/api/cloud/*` | 各种 | 云管理 | +| Endpoint | Method | Description | +| ---------------------- | ------- | --------------------- | +| `/api/sync/cloud` | Various | Cloud sync operations | +| `/api/sync/initialize` | POST | Initialize sync | +| `/api/cloud/*` | Various | Cloud management | -### CLI 工具 +### CLI Tools -| 端点 | 方法 | 描述 | -| ---------------------------------- | ---- | ----------------- | -| `/api/cli-tools/claude-settings` | 获取 | 克劳德 CLI 状态 | -| `/api/cli-tools/codex-settings` | 获取 | Codex CLI 状态 | -| `/api/cli-tools/droid-settings` | 获取 | Droid CLI 状态 | -| `/api/cli-tools/openclaw-settings` | 获取 | OpenClaw CLI 状态 | -| `/api/cli-tools/runtime/[toolId]` | 获取 | 通用 CLI 运行时 | +| Endpoint | Method | Description | +| ---------------------------------- | ------ | ------------------- | +| `/api/cli-tools/claude-settings` | GET | Claude CLI status | +| `/api/cli-tools/codex-settings` | GET | Codex CLI status | +| `/api/cli-tools/droid-settings` | GET | Droid CLI status | +| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status | +| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime | -CLI 响应包括：`installed`、`runnable`、`command`、`commandPath`、`runtimeMode`、`reason`。 +CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. -### 弹性和速率限制 +### ACP Agents -| 端点 | 方法 | 描述 | -| ----------------------- | --------- | ---------------------- | -| `/api/resilience` | 获取/放置 | 获取/更新弹性配置文件 | -| `/api/resilience/reset` | 发布 | 重置断路器 | -| `/api/rate-limits` | 获取 | 每个帐户的速率限制状态 | -| `/api/rate-limit` | 获取 | 全局限速配置 | +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | -### 评估 +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). -| 端点 | 方法 | 描述 | -| ------------ | --------- | --------------------- | -| `/api/evals` | 获取/发布 | 列出评估套件/运行评估 | +### Resilience & Rate Limits -### 政策 +| Endpoint | Method | Description | +| ----------------------- | ------- | ------------------------------- | +| `/api/resilience` | GET/PUT | Get/update resilience profiles | +| `/api/resilience/reset` | POST | Reset circuit breakers | +| `/api/rate-limits` | GET | Per-account rate limit status | +| `/api/rate-limit` | GET | Global rate limit configuration | -| 端点 | 方法 | 描述 | -| --------------- | -------------- | ------------ | -| `/api/policies` | 获取/发布/删除 | 管理路由策略 | +### Evals -### 合规性 +| Endpoint | Method | Description | +| ------------ | -------- | --------------------------------- | +| `/api/evals` | GET/POST | List eval suites / run evaluation | -|端点 |方法|描述 | -| ------------------------ | | ------ | -------------------------------------- | -| `/api/compliance/audit-log` |获取 |合规审核日志（最后 N）| +### Policies -### v1beta（Gemini 兼容） +| Endpoint | Method | Description | +| --------------- | --------------- | ----------------------- | +| `/api/policies` | GET/POST/DELETE | Manage routing policies | -| 端点 | 方法 | 描述 | -| -------------------------- | ---- | ----------------------------- | -| `/v1beta/models` | 获取 | 以 Gemini 格式列出模型 | -| `/v1beta/models/{...path}` | 发布 | Gemini `generateContent` 端点 | +### Compliance -这些端点反映了 Gemini 的 API 格式，适用于期望本机 Gemini SDK 兼容性的客户端。 +| Endpoint | Method | Description | +| --------------------------- | ------ | ----------------------------- | +| `/api/compliance/audit-log` | GET | Compliance audit log (last N) | -### 内部/系统 API +### v1beta (Gemini-Compatible) -| 端点 | 方法 | 描述 | -| --------------- | ---- | ------------------------------------------- | -| `/api/init` | 获取 | 应用程序初始化检查（首次运行时使用） | -| `/api/tags` | 获取 | Ollama 兼容模型标签（适用于 Ollama 客户端） | -| `/api/restart` | 发布 | 触发服务器优雅重启 | -| `/api/shutdown` | 发布 | 触发服务器正常关闭 | +| Endpoint | Method | Description | +| -------------------------- | ------ | --------------------------------- | +| `/v1beta/models` | GET | List models in Gemini format | +| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint | -> **注意：** 这些端点由系统内部使用或用于 Ollama 客户端兼容性。最终用户通常不会调用它们。 +These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility. + +### Internal / System APIs + +| Endpoint | Method | Description | +| --------------- | ------ | ---------------------------------------------------- | +| `/api/init` | GET | Application initialization check (used on first run) | +| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) | +| `/api/restart` | POST | Trigger graceful server restart | +| `/api/shutdown` | POST | Trigger graceful server shutdown | + +> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users. --- -## 音频转录 +## Audio Transcription ```bash POST /v1/audio/transcriptions @@ -317,9 +327,9 @@ Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` -使用 Deepgram 或 AssemblyAI 转录音频文件。 +Transcribe audio files using Deepgram or AssemblyAI. -**要求：** +**Request:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ @@ -328,7 +338,7 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -**回应：** +**Response:** ```json { @@ -339,15 +349,15 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ } ``` -**支持的提供商：** `deepgram/nova-3`、`assemblyai/best`。 +**Supported providers:** `deepgram/nova-3`, `assemblyai/best`. -**支持的格式：** `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。 +**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -## 奥拉马兼容性 +## Ollama Compatibility -对于使用 Ollama 的 API 格式的客户端： +For clients that use Ollama's API format: ```bash # Chat endpoint (Ollama format) @@ -357,18 +367,18 @@ POST /v1/api/chat GET /api/tags ``` -请求会在 Ollama 和内部格式之间自动转换。 +Requests are automatically translated between Ollama and internal formats. --- -## 遥测 +## Telemetry ```bash # Get latency telemetry summary (p50/p95/p99 per provider) GET /api/telemetry/summary ``` -**回应：** +**Response:** ```json { @@ -381,7 +391,7 @@ GET /api/telemetry/summary --- -## 预算 +## Budget ```bash # Get budget status for all API keys @@ -400,7 +410,7 @@ Content-Type: application/json --- -## 型号可用性 +## Model Availability ```bash # Get real-time model availability across all providers @@ -417,25 +427,25 @@ Content-Type: application/json --- -## 请求处理 +## Request Processing -1. 客户端向`/v1/*`发送请求 -2. 路由处理程序调用 `handleChat`、`handleEmbedding`、`handleAudioTranscription` 或 `handleImageGeneration` -3. 模型已解析（直接提供者/模型或别名/组合） -4. 通过帐户可用性过滤从本地数据库中选择凭证 -5. 对于聊天：`handleChatCore` — 格式检测、翻译、缓存检查、幂等性检查 -6. Provider执行器发送上游请求 -7. 响应转换回客户端格式（聊天）或按原样返回（嵌入/图像/音频） -8. 使用/日志记录 -9. 根据组合规则对错误应用回退 +1. Client sends request to `/v1/*` +2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration` +3. Model is resolved (direct provider/model or alias/combo) +4. Credentials selected from local DB with account availability filtering +5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check +6. Provider executor sends upstream request +7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio) +8. Usage/logging recorded +9. Fallback applies on errors according to combo rules -完整架构参考：[link](ARCHITECTURE.md) +Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md) --- -## 身份验证 +## Authentication -- 仪表板路由 (`/dashboard/*`) 使用 `auth_token` cookie -- 登录使用保存的密码哈希；回退到 `INITIAL_PASSWORD` -- `requireLogin` 可通过 `/api/settings/require-login` 切换 -- `/v1/*` 路由在 `REQUIRE_API_KEY=true` 时可选择需要 Bearer API 密钥 +- Dashboard routes (`/dashboard/*`) use `auth_token` cookie +- Login uses saved password hash; fallback to `INITIAL_PASSWORD` +- `requireLogin` toggleable via `/api/settings/require-login` +- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true` diff --git a/docs/i18n/zh-CN/ARCHITECTURE.md b/docs/i18n/zh-CN/ARCHITECTURE.md index 1efcb653d0..258d62df53 100644 --- a/docs/i18n/zh-CN/ARCHITECTURE.md +++ b/docs/i18n/zh-CN/ARCHITECTURE.md @@ -1,71 +1,71 @@ -# OmniRoute 架构 +# OmniRoute Architecture -🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) +🌐 **Languages:** 🇺🇸 [English](ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) -_最后更新：2026-02-18_ +_Last updated: 2026-03-04_ -## 执行摘要 +## Executive Summary -OmniRoute 是基于 Next.js 构建的本地 AI 路由网关和仪表板。 -它提供单个 OpenAI 兼容端点 (`/v1/*`)，并通过转换、回退、令牌刷新和使用跟踪在多个上游提供商之间路由流量。 +OmniRoute is a local AI routing gateway and dashboard built on Next.js. +It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking. -核心能力： +Core capabilities: -- 用于 CLI/工具的 OpenAI 兼容 API 界面（28 个提供商） -- 跨提供商格式的请求/响应翻译 -- 模型组合后备（多模型序列） -- 账户级回退（每个提供商多个账户） -- OAuth + API 密钥提供商连接管理 -- 通过 `/v1/embeddings` 嵌入生成（6 个提供商，9 个模型） -- 通过 `/v1/images/generations` 生成图像（4 个提供商，9 个模型） -- 为推理模型考虑标签解析（`...`） -- 响应清理以实现严格的 OpenAI SDK 兼容性 -- 角色标准化（开发人员→系统、系统→用户）以实现跨提供商兼容性 -- 结构化输出转换（json_schema→Gemini responseSchema） -- 提供商、密钥、别名、组合、设置、定价的本地持久性 -- 使用/成本跟踪和请求记录 -- 可选的云同步用于多设备/状态同步 -- API 访问控制的 IP 允许列表/阻止列表 -- 思考预算管理（直通/自动/自定义/自适应） -- 全局系统提示注入 -- 会话跟踪和指纹识别 -- 使用特定于提供商的配置文件增强每个帐户的速率限制 -- 提供者弹性的断路器模式 -- 具有互斥锁的防雷群保护 -- 基于签名的请求重复数据删除缓存 -- 领域层：模型可用性、成本规则、后备策略、锁定策略 -- 域状态持久性（用于回退、预算、锁定、断路器的 SQLite 直写式缓存） -- 用于集中请求评估的策略引擎（锁定→预算→后备） -- 使用 p50/p95/p99 延迟聚合请求遥测 -- 用于端到端跟踪的关联 ID (X-Request-Id) -- 合规性审核日志记录，可根据 API 密钥选择退出 -- LLM质量保证评估框架 -- 具有实时断路器状态的 Resilience UI 仪表板 -- 模块化 OAuth 提供程序（`src/lib/oauth/providers/` 下有 12 个单独的模块） +- OpenAI-compatible API surface for CLI/tools (28 providers) +- Request/response translation across provider formats +- Model combo fallback (multi-model sequence) +- Account-level fallback (multi-account per provider) +- OAuth + API-key provider connection management +- Embedding generation via `/v1/embeddings` (6 providers, 9 models) +- Image generation via `/v1/images/generations` (4 providers, 9 models) +- Think tag parsing (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developer→system, system→user) for cross-provider compatibility +- Structured output conversion (json_schema → Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout → budget → fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) -主要运行时模型： +Primary runtime model: -- `src/app/api/*` 下的 Next.js 应用程序路由同时实现仪表板 API 和兼容性 API -- `src/sse/*` + `open-sse/*` 中的共享 SSE/路由核心处理提供程序执行、转换、流式传输、回退和使用 +- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs +- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage -## 范围和边界 +## Scope and Boundaries -### 在范围内 +### In Scope -- 本地网关运行时 -- 仪表板管理 API -- 提供商身份验证和令牌刷新 -- 请求翻译和 SSE 流媒体 -- 本地状态+使用持久性 -- 可选的云同步编排 +- Local gateway runtime +- Dashboard management APIs +- Provider authentication and token refresh +- Request translation and SSE streaming +- Local state + usage persistence +- Optional cloud sync orchestration -### 超出范围 +### Out of Scope -- `NEXT_PUBLIC_CLOUD_URL` 背后的云服务实现 -- 本地流程之外的提供商 SLA/控制平面 -- 外部 CLI 二进制文件本身（Claude CLI、Codex CLI 等） +- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL` +- Provider SLA/control plane outside local process +- External CLI binaries themselves (Claude CLI, Codex CLI, etc.) -## 高级系统上下文 +## High-Level System Context ```mermaid flowchart LR @@ -81,8 +81,8 @@ flowchart LR API[V1 Compatibility API\n/v1/*] DASH[Dashboard + Management API\n/api/*] CORE[SSE + Translation Core\nopen-sse + src/sse] - DB[(db.json)] - UDB[(usage.json + log.txt)] + DB[(storage.sqlite)] + UDB[(usage tables + log artifacts)] end subgraph Upstreams[Upstream Providers] @@ -113,151 +113,152 @@ flowchart LR DASH --> CLOUD ``` -## 核心运行时组件 +## Core Runtime Components -## 1) API 和路由层（Next.js 应用程序路由） +## 1) API and Routing Layer (Next.js App Routes) -主要目录： +Main directories: -- `src/app/api/v1/*` 和 `src/app/api/v1beta/*` 用于兼容性 API -- `src/app/api/*` 用于管理/配置 API -- 接下来重写 `next.config.mjs` 将 `/v1/*` 映射到 `/api/v1/*` +- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs +- `src/app/api/*` for management/configuration APIs +- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*` -重要的兼容性路线： +Important compatibility routes: - `src/app/api/v1/chat/completions/route.ts` - `src/app/api/v1/messages/route.ts` - `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` — 包括带有 `custom: true` 的自定义模型 -- `src/app/api/v1/embeddings/route.ts` — 嵌入生成（6 个提供商） -- `src/app/api/v1/images/generations/route.ts` — 图像生成（4 个以上提供商，包括 Antigravity/Nebius） +- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true` +- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers) +- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius) - `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — 每个提供商专用的聊天 -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — 每个提供商专用的嵌入 -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — 每个提供商专用的图像 +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images - `src/app/api/v1beta/models/route.ts` - `src/app/api/v1beta/models/[...path]/route.ts` -管理域： +Management domains: -- 身份验证/设置：`src/app/api/auth/*`、`src/app/api/settings/*` -- 提供商/连接：`src/app/api/providers*` -- 提供商节点：`src/app/api/provider-nodes*` -- 自定义模型：`src/app/api/provider-models`（获取/发布/删除） -- 模型目录：`src/app/api/models/catalog` (GET) -- 代理配置：`src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth：`src/app/api/oauth/*` -- 密钥/别名/组合/定价：`src/app/api/keys*`、`src/app/api/models/alias`、`src/app/api/combos*`、`src/app/api/pricing` -- 用法：`src/app/api/usage/*` -- 同步/云：`src/app/api/sync/*`、`src/app/api/cloud/*` -- CLI 工具助手：`src/app/api/cli-tools/*` -- IP 过滤器：`src/app/api/settings/ip-filter` (GET/PUT) -- 思考预算：`src/app/api/settings/thinking-budget` (GET/PUT) -- 系统提示：`src/app/api/settings/system-prompt` (GET/PUT) -- 会话：`src/app/api/sessions` (GET) -- 速率限制：`src/app/api/rate-limits` (GET) -- 弹性：`src/app/api/resilience` (GET/PATCH) — 提供商配置文件、断路器、速率限制状态 -- 弹性重置：`src/app/api/resilience/reset` (POST) — 重置断路器 + 冷却时间 -- 缓存统计信息：`src/app/api/cache/stats`（获取/删除） -- 模型可用性：`src/app/api/models/availability` (GET/POST) -- 遥测：`src/app/api/telemetry/summary` (GET) -- 预算：`src/app/api/usage/budget`（获取/发布） -- 后备链：`src/app/api/fallback/chains` (GET/POST/DELETE) -- 合规审核：`src/app/api/compliance/audit-log` (GET) -- 评估：`src/app/api/evals` (GET/POST)、`src/app/api/evals/[suiteId]` (GET) -- 政策：`src/app/api/policies` (GET/POST) +- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*` +- Providers/connections: `src/app/api/providers*` +- Provider nodes: `src/app/api/provider-nodes*` +- Custom models: `src/app/api/provider-models` (GET/POST/DELETE) +- Model catalog: `src/app/api/models/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) -## 2) SSE + 翻译核心 +## 2) SSE + Translation Core -主要流程模块： +Main flow modules: -- 条目：`src/sse/handlers/chat.ts` -- 核心编排：`open-sse/handlers/chatCore.ts` -- 提供者执行适配器：`open-sse/executors/*` -- 格式检测/提供商配置：`open-sse/services/provider.ts` -- 模型解析/解析：`src/sse/services/model.ts`、`open-sse/services/model.ts` -- 账户后备逻辑：`open-sse/services/accountFallback.ts` -- 翻译注册表：`open-sse/translator/index.ts` -- 流转换：`open-sse/utils/stream.ts`、`open-sse/utils/streamHandler.ts` -- 使用提取/标准化：`open-sse/utils/usageTracking.ts` -- 思考标签解析器：`open-sse/utils/thinkTagParser.ts` -- 嵌入处理程序：`open-sse/handlers/embeddings.ts` -- 嵌入提供程序注册表：`open-sse/config/embeddingRegistry.ts` -- 图像生成处理程序：`open-sse/handlers/imageGeneration.ts` -- 图像提供者注册表：`open-sse/config/imageRegistry.ts` -- 响应清理：`open-sse/handlers/responseSanitizer.ts` -- 角色规范化：`open-sse/services/roleNormalizer.ts` +- Entry: `src/sse/handlers/chat.ts` +- Core orchestration: `open-sse/handlers/chatCore.ts` +- Provider execution adapters: `open-sse/executors/*` +- Format detection/provider config: `open-sse/services/provider.ts` +- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Account fallback logic: `open-sse/services/accountFallback.ts` +- Translation registry: `open-sse/translator/index.ts` +- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Usage extraction/normalization: `open-sse/utils/usageTracking.ts` +- Think tag parser: `open-sse/utils/thinkTagParser.ts` +- Embedding handler: `open-sse/handlers/embeddings.ts` +- Embedding provider registry: `open-sse/config/embeddingRegistry.ts` +- Image generation handler: `open-sse/handlers/imageGeneration.ts` +- Image provider registry: `open-sse/config/imageRegistry.ts` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.ts` -服务（业务逻辑）： +Services (business logic): -- 账户选择/评分：`open-sse/services/accountSelector.ts` -- 上下文生命周期管理：`open-sse/services/contextManager.ts` -- IP 过滤器强制执行：`open-sse/services/ipFilter.ts` -- 会话跟踪：`open-sse/services/sessionManager.ts` -- 请求重复数据删除：`open-sse/services/signatureCache.ts` -- 系统提示注入：`open-sse/services/systemPrompt.ts` -- 思考预算管理：`open-sse/services/thinkingBudget.ts` -- 通配符模型路由：`open-sse/services/wildcardRouter.ts` -- 速率限制管理：`open-sse/services/rateLimitManager.ts` -- 断路器：`open-sse/services/circuitBreaker.ts` +- Account selection/scoring: `open-sse/services/accountSelector.ts` +- Context lifecycle management: `open-sse/services/contextManager.ts` +- IP filter enforcement: `open-sse/services/ipFilter.ts` +- Session tracking: `open-sse/services/sessionManager.ts` +- Request deduplication: `open-sse/services/signatureCache.ts` +- System prompt injection: `open-sse/services/systemPrompt.ts` +- Thinking budget management: `open-sse/services/thinkingBudget.ts` +- Wildcard model routing: `open-sse/services/wildcardRouter.ts` +- Rate limit management: `open-sse/services/rateLimitManager.ts` +- Circuit breaker: `open-sse/services/circuitBreaker.ts` -领域层模块： +Domain layer modules: -- 型号可用性：`src/lib/domain/modelAvailability.ts` -- 成本规则/预算：`src/lib/domain/costRules.ts` -- 后备政策：`src/lib/domain/fallbackPolicy.ts` -- 组合解析器：`src/lib/domain/comboResolver.ts` -- 锁定政策：`src/lib/domain/lockoutPolicy.ts` -- 策略引擎：`src/domain/policyEngine.ts` — 集中锁定→预算→后备评估 -- 错误代码目录：`src/lib/domain/errorCodes.ts` -- 请求 ID：`src/lib/domain/requestId.ts` -- 获取超时：`src/lib/domain/fetchTimeout.ts` -- 请求遥测：`src/lib/domain/requestTelemetry.ts` -- 合规/审计：`src/lib/domain/compliance/index.ts` -- 评估跑步者：`src/lib/domain/evalRunner.ts` -- 域状态持久性：`src/lib/db/domainState.ts` — 用于后备链、预算、成本历史记录、锁定状态、断路器的 SQLite CRUD +- Model availability: `src/lib/domain/modelAvailability.ts` +- Cost rules/budgets: `src/lib/domain/costRules.ts` +- Fallback policy: `src/lib/domain/fallbackPolicy.ts` +- Combo resolver: `src/lib/domain/comboResolver.ts` +- Lockout policy: `src/lib/domain/lockoutPolicy.ts` +- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation +- Error codes catalog: `src/lib/domain/errorCodes.ts` +- Request ID: `src/lib/domain/requestId.ts` +- Fetch timeout: `src/lib/domain/fetchTimeout.ts` +- Request telemetry: `src/lib/domain/requestTelemetry.ts` +- Compliance/audit: `src/lib/domain/compliance/index.ts` +- Eval runner: `src/lib/domain/evalRunner.ts` +- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers -OAuth 提供程序模块（`src/lib/oauth/providers/` 下有 12 个单独的文件）： +OAuth provider modules (12 individual files under `src/lib/oauth/providers/`): -- 注册表索引：`src/lib/oauth/providers/index.ts` -- 个人提供商：`claude.ts`、`codex.ts`、`gemini.ts`、`antigravity.ts`、`iflow.ts`、`qwen.ts`、`kimi-coding.ts`、`github.ts`、 `kiro.ts`、`cursor.ts`、`kilocode.ts`、`cline.ts` -- 薄包装器：`src/lib/oauth/providers.ts` — 从各个模块重新导出 +- Registry index: `src/lib/oauth/providers/index.ts` +- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules -## 3) 持久层 +## 3) Persistence Layer -主状态数据库： +Primary state DB (SQLite): -- `src/lib/localDb.ts` -- 文件：`${DATA_DIR}/db.json`（或设置时为 `$XDG_CONFIG_HOME/omniroute/db.json`，否则为 `~/.omniroute/db.json`） -- 实体：providerConnections、providerNodes、modelAliases、组合、apiKeys、设置、定价、**customModels**、**proxyConfig**、**ipFilter**、**thinkingBudget**、**systemPrompt** +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** -使用数据库： +Usage persistence: -- `src/lib/usageDb.ts` -- 文件：`${DATA_DIR}/usage.json`、`${DATA_DIR}/log.txt`、`${DATA_DIR}/call_logs/` -- 遵循与 `localDb` 相同的基本目录策略（`DATA_DIR`，然后设置时为 `XDG_CONFIG_HOME/omniroute`） -- 分解为重点子模块：`migrations.ts`、`usageHistory.ts`、`costCalculator.ts`、`usageStats.ts`、`callLogs.ts` +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present -域状态数据库（SQLite）： +Domain State DB (SQLite): -- `src/lib/db/domainState.ts` — 域状态的 CRUD 操作 -- 表（在 `src/lib/db/core.ts` 中创建）：`domain_fallback_chains`、`domain_budgets`、`domain_cost_history`、`domain_lockout_state`、`domain_circuit_breakers` -- 直写式缓存模式：内存中的Map在运行时具有权威性；突变同步写入SQLite；冷启动时从数据库恢复状态 +- `src/lib/db/domainState.ts` — CRUD operations for domain state +- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start -## 4) 身份验证 + 安全表面 +## 4) Auth + Security Surfaces -- 仪表板 cookie 身份验证：`src/proxy.ts`、`src/app/api/auth/login/route.ts` -- API 密钥生成/验证：`src/shared/utils/apiKey.ts` -- 提供商机密保留在 `providerConnections` 条目中 -- 通过 `open-sse/utils/proxyFetch.ts` （环境变量）和 `open-sse/utils/networkProxy.ts` （可按提供商配置或全局配置）提供出站代理支持 +- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API key generation/verification: `src/shared/utils/apiKey.ts` +- Provider secrets persisted in `providerConnections` entries +- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global) -## 5) 云同步 +## 5) Cloud Sync -- 调度程序初始化：`src/lib/initCloudSync.ts`、`src/shared/services/initializeCloudSync.ts` -- 定期任务：`src/shared/services/cloudSyncScheduler.ts` -- 控制路线：`src/app/api/sync/cloud/route.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Control route: `src/app/api/sync/cloud/route.ts` -## 请求生命周期 (`/v1/chat/completions`) +## Request Lifecycle (`/v1/chat/completions`) ```mermaid sequenceDiagram @@ -304,7 +305,7 @@ sequenceDiagram Stream->>Usage: extract usage + persist history/log ``` -## 组合 + 账户回退流程 +## Combo + Account Fallback Flow ```mermaid flowchart TD @@ -334,9 +335,9 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -回退决策由 `open-sse/services/accountFallback.ts` 使用状态代码和错误消息启发法驱动。 +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. -## OAuth 加入和令牌刷新生命周期 +## OAuth Onboarding and Token Refresh Lifecycle ```mermaid sequenceDiagram @@ -366,9 +367,9 @@ sequenceDiagram Test-->>UI: validation result ``` -实时流量期间的刷新通过执行器 `refreshCredentials()` 在 `open-sse/handlers/chatCore.ts` 内执行。 +Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`. -## 云同步生命周期（启用/同步/禁用） +## Cloud Sync Lifecycle (Enable / Sync / Disable) ```mermaid sequenceDiagram @@ -400,9 +401,9 @@ sequenceDiagram Sync-->>UI: disabled ``` -启用云时，定期同步由 `CloudSyncScheduler` 触发。 +Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled. -## 数据模型和存储映射 +## Data Model and Storage Map ```mermaid erDiagram @@ -503,14 +504,14 @@ erDiagram } ``` -物理存储文件： +Physical storage files: -- 主状态：`${DATA_DIR}/db.json`（或设置时为 `$XDG_CONFIG_HOME/omniroute/db.json`，否则为 `~/.omniroute/db.json`） -- 使用统计数据：`${DATA_DIR}/usage.json` -- 请求日志行：`${DATA_DIR}/log.txt` -- 可选转换器/请求调试会话：`/logs/...` +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` -## 部署拓扑 +## Deployment Topology ```mermaid flowchart LR @@ -522,8 +523,8 @@ flowchart LR subgraph ContainerOrProcess[OmniRoute Runtime] Next[Next.js Server\nPORT=20128] Core[SSE Core + Executors] - MainDB[(db.json)] - UsageDB[(usage.json/log.txt)] + MainDB[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] end subgraph External[External Services] @@ -541,241 +542,242 @@ flowchart LR Next --> SyncCloud ``` -## 模块映射（决策关键） +## Module Mapping (Decision-Critical) -### 路由和 API 模块 +### Route and API Modules -- `src/app/api/v1/*`、`src/app/api/v1beta/*`：兼容性 API -- `src/app/api/v1/providers/[provider]/*`：每个提供商的专用路由（聊天、嵌入、图像） -- `src/app/api/providers*`：提供商 CRUD、验证、测试 -- `src/app/api/provider-nodes*`：自定义兼容节点管理 -- `src/app/api/provider-models`：自定义模型管理（CRUD） -- `src/app/api/models/catalog`：完整模型目录 API（所有类型按提供商分组） -- `src/app/api/oauth/*`：OAuth/设备代码流 -- `src/app/api/keys*`：本地 API 密钥生命周期 -- `src/app/api/models/alias`：别名管理 -- `src/app/api/combos*`：后备组合管理 -- `src/app/api/pricing`：成本计算的定价覆盖 -- `src/app/api/settings/proxy`：代理配置（GET/PUT/DELETE） -- `src/app/api/settings/proxy/test`：出站代理连接测试 (POST) -- `src/app/api/usage/*`：使用和日志 API -- `src/app/api/sync/*` + `src/app/api/cloud/*`：云同步和面向云的助手 -- `src/app/api/cli-tools/*`：本地 CLI 配置编写器/检查器 -- `src/app/api/settings/ip-filter`：IP 允许列表/阻止列表 (GET/PUT) -- `src/app/api/settings/thinking-budget`：思考代币预算配置（GET/PUT） -- `src/app/api/settings/system-prompt`：全局系统提示符（GET/PUT） -- `src/app/api/sessions`：活动会话列表 (GET) -- `src/app/api/rate-limits`：每个账户的速率限制状态 (GET) +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) -### 路由和执行核心 +### Routing and Execution Core -- `src/sse/handlers/chat.ts`：请求解析、组合处理、帐户选择循环 -- `open-sse/handlers/chatCore.ts`：翻译、执行程序调度、重试/刷新处理、流设置 -- `open-sse/executors/*`：提供商特定的网络和格式行为 +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior -### 翻译注册表和格式转换器 +### Translation Registry and Format Converters -- `open-sse/translator/index.ts`：翻译器注册和编排 -- 请求翻译：`open-sse/translator/request/*` -- 回复翻译器：`open-sse/translator/response/*` -- 格式常量：`open-sse/translator/formats.ts` +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` -### 坚持 +### Persistence -- `src/lib/localDb.ts`：持久配置/状态 -- `src/lib/usageDb.ts`：使用历史记录和滚动请求日志 +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables -## 提供者执行者覆盖范围（策略模式） +## Provider Executor Coverage (Strategy Pattern) -每个提供程序都有一个扩展 `BaseExecutor`（在 `open-sse/executors/base.ts` 中）的专用执行器，它提供 URL 构建、标头构建、指数退避重试、凭证刷新挂钩和 `execute()` 编排方法。 +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. -| 执行人 | 提供商 | 特殊处理 | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------ | -| `DefaultExecutor` | OpenAI、Claude、Gemini、Qwen、iFlow、OpenRouter、GLM、Kimi、MiniMax、DeepSeek、Groq、xAI、Mistral、Perplexity、Together、Fireworks、Cerebras、Cohere、NVIDIA | 每个提供商的动态 URL/标头配置 | -| `AntigravityExecutor` | 谷歌反重力 | 自定义项目/会话 ID，解析后重试 | -| `CodexExecutor` | OpenAI 法典 | 注入系统指令，强制推理工作 | -| `CursorExecutor` | 光标IDE | ConnectRPC 协议、Protobuf 编码、通过校验和进行请求签名 | -| `GithubExecutor` | GitHub 副驾驶 | Copilot 令牌刷新，模仿 VSCode 标头 | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS CodeWhisperer/Kiro | AWS CodeWhisperer/Kiro AWS EventStream 二进制格式 → SSE 转换 | -| `GeminiCLIExecutor` | 双子座 CLI | Google OAuth 令牌刷新周期 | +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider | +| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing | +| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort | +| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum | +| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle | -所有其他提供商（包括自定义兼容节点）都使用 `DefaultExecutor`。 +All other providers (including custom compatible nodes) use the `DefaultExecutor`. -## 提供商兼容性矩阵 +## Provider Compatibility Matrix -| 供应商 | 格式 | 授权 | 流 | 非流 | 令牌刷新 | 使用API​​ | -| ---------------- | ----------- | ------------------ | ------------ | ------------------------- | -------- | -------------- | ----------- | -| 克劳德 | 克劳德 | API 密钥/OAuth | ✅ | ✅ | ✅ | ⚠️ 仅限管理员 | -| 双子座 | 双子座 | API 密钥/OAuth | ✅ | ✅ | ✅ | ⚠️ 云控制台 | -| 双子座 CLI | Gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ 云控制台 | -| 反重力 | 反重力 | OAuth | ✅ | ✅ | ✅ | ✅ 完整配额API | -| 开放人工智能 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| 法典 | openai-回应 | OAuth | ✅ 强迫 | ❌ | ✅ | ✅ 速率限制 | -| GitHub 副驾驶 | 开放 | OAuth + 副驾驶令牌 | ✅ | ✅ | ✅ | ✅ 配额快照 | -| 光标 | 光标 | 自定义校验和 | ✅ | ✅ | ❌ | ❌ | -| 基罗 | 基罗 | AWS SSO OIDC | AWS SSO OIDC | AWS SSO OIDC ✅（事件流） | ❌ | ✅ | ✅ 使用限制 | -| 奎文 | 开放 | OAuth | ✅ | ✅ | ✅ | ⚠️ 根据要求 | -| iFlow | 开放 | OAuth（基本） | ✅ | ✅ | ✅ | ⚠️ 根据要求 | -| 开放路由器 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| GLM/Kimi/MiniMax | 克劳德 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| 深度搜索 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| 格罗克 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| xAI (Grok) | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| 米斯特拉尔 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| 困惑 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| 一起人工智能 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| 烟花人工智能 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| 大脑 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| 连贯 | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | -| NVIDIA NIM | 开放 | API 密钥 | ✅ | ✅ | ❌ | ❌ | +| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API | +| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ | +| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only | +| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API | +| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits | +| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots | +| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request | +| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request | +| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ | -## 格式翻译覆盖范围 +## Format Translation Coverage -检测到的源格式包括： +Detected source formats include: - `openai` - `openai-responses` - `claude` - `gemini` -目标格式包括： +Target formats include: -- OpenAI 聊天/回复 - ——克劳德 -- Gemini/Gemini-CLI/反重力信封 -- 基罗 -- 光标 +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor -翻译使用 **OpenAI 作为中心格式** - 所有转换都通过 OpenAI 作为中间： +Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate: ``` Source Format → OpenAI (hub) → Target Format ``` -根据源有效负载形状和提供程序目标格式动态选择翻译。 +Translations are selected dynamically based on source payload shape and provider target format. -翻译管道中的附加处理层： +Additional processing layers in the translation pipeline: -- **响应清理** — 从 OpenAI 格式响应（流式和非流式）中去除非标准字段，以确保严格的 SDK 合规性 -- **角色标准化** — 对于非 OpenAI 目标，将 `developer` → `system` 转换；对于拒绝系统角色的模型（GLM、ERNIE），合并 `system` → `user` -- **思考标签提取** — 将内容中的 `...` 块解析为 `reasoning_content` 字段 -- **结构化输出** — 将 OpenAI `response_format.json_schema` 转换为 Gemini 的 `responseMimeType` + `responseSchema` +- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** — Parses `...` blocks from content into `reasoning_content` field +- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` -## 支持的 API 端点 +## Supported API Endpoints -| 端点 | 格式 | 处理程序 | -| -------------------------------------------------- | --------------- | --------------------------------------- | -| `POST /v1/chat/completions` | OpenAI 聊天 | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | 克劳德消息 | 相同的处理程序（自动检测） | -| `POST /v1/responses` | OpenAI 回应 | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI 嵌入 | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | 型号列表 | API路线 | -| `POST /v1/images/generations` | OpenAI 图像 | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | 型号列表 | API路线 | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI 聊天 | 专用于每个提供商的模型验证 | -| `POST /v1/providers/{provider}/embeddings` | OpenAI 嵌入 | 专用于每个提供商的模型验证 | -| `POST /v1/providers/{provider}/images/generations` | OpenAI 图像 | 专用于每个提供商的模型验证 | -| `POST /v1/messages/count_tokens` | 克劳德代币计数 | API路线 | -| `GET /v1/models` | OpenAI 模型列表 | API路线（聊天+嵌入+图像+自定义模型） | -| `GET /api/models/catalog` | 目录 | 所有模型按提供商+类型分组 | -| `POST /v1beta/models/*:streamGenerateContent` | 双子座人 | API路线 | -| `GET/PUT/DELETE /api/settings/proxy` | 代理配置 | 网络代理配置 | -| `POST /api/settings/proxy/test` | 代理连接 | 代理运行状况/连接测试端点 | -| `GET/POST/DELETE /api/provider-models` | 定制型号 | 每个提供商的自定义模型管理 | +| Endpoint | Format | Handler | +| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) | +| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Model listing | API route | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Model listing | API route | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation | +| `POST /v1/messages/count_tokens` | Claude Token Count | API route | +| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) | +| `GET /api/models/catalog` | Catalog | All models grouped by provider + type | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration | +| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint | +| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider | -## 绕过处理程序 +## Bypass Handler -旁路处理程序 (`open-sse/utils/bypassHandler.ts`) 拦截来自 Claude CLI 的已知“一次性”请求（预热 ping、标题提取和令牌计数），并返回 **虚假响应**，而不消耗上游提供商令牌。仅当 `User-Agent` 包含 `claude-cli` 时才会触发。 +The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`. -## 请求记录器管道 +## Request Logger Pipeline -请求记录器 (`open-sse/utils/requestLogger.ts`) 提供 7 阶段调试日志记录管道，默认情况下禁用，通过 `ENABLE_REQUEST_LOGS=true` 启用： +The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`: ``` 1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json → 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt ``` -每个请求会话的文件都会写入 `/logs//`。 +Files are written to `/logs//` for each request session. -## 故障模式和恢复能力 +## Failure Modes and Resilience -## 1) 帐户/提供商可用性 +## 1) Account/Provider Availability -- 提供商帐户因瞬态/速率/身份验证错误而冷却 -- 请求失败之前的帐户回退 -- 当前模型/提供商路径耗尽时组合模型回退 +- provider account cooldown on transient/rate/auth errors +- account fallback before failing request +- combo model fallback when current model/provider path is exhausted -## 2) 令牌到期 +## 2) Token Expiry -- 对可刷新提供程序进行预检查和刷新并重试 -- 401/403 在核心路径中尝试刷新后重试 +- pre-check and refresh with retry for refreshable providers +- 401/403 retry after refresh attempt in core path -## 3) 流安全 +## 3) Stream Safety -- 断开连接感知流控制器 -- 具有流尾刷新和 `[DONE]` 处理的翻译流 -- 当提供者使用元数据丢失时使用估计回退 +- disconnect-aware stream controller +- translation stream with end-of-stream flush and `[DONE]` handling +- usage estimation fallback when provider usage metadata is missing -## 4) 云同步降级 +## 4) Cloud Sync Degradation -- 出现同步错误，但本地运行时仍在继续 -- 调度程序具有可重试的逻辑，但定期执行当前默认调用单次尝试同步 +- sync errors are surfaced but local runtime continues +- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default -## 5) 数据完整性 +## 5) Data Integrity -- 数据库形状迁移/修复丢失的键 -- localDb 和 useDb 的损坏的 JSON 重置保护措施 +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON → SQLite migration compatibility path -## 可观察性和操作信号 +## Observability and Operational Signals -运行时可见性来源： +Runtime visibility sources: -- 来自 `src/sse/utils/logger.ts` 的控制台日志 -- 每个请求的使用情况汇总在 `usage.json` 中 -- `log.txt` 中的文本请求状态日志 -- 当 `ENABLE_REQUEST_LOGS=true` 时，`logs/` 下的可选深度请求/翻译日志 -- UI 使用的仪表板使用端点 (`/api/usage/*`) +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption -## 安全敏感边界 +## Security-Sensitive Boundaries -- JWT 秘密 (`JWT_SECRET`) 确保仪表板会话 cookie 验证/签名 -- 在实际部署中必须覆盖初始密码回退（`INITIAL_PASSWORD`，默认 `123456`） -- API 密钥 HMAC 秘密 (`API_KEY_SECRET`) 确保生成的本地 API 密钥格式的安全 -- 提供者机密（API 密钥/令牌）保留在本地数据库中，并应在文件系统级别受到保护 -- 云同步端点依赖于 API 密钥身份验证 + 机器 ID 语义 +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics -## 环境和运行时矩阵 +## Environment and Runtime Matrix -代码主动使用的环境变量： +Environment variables actively used by code: -- 应用程序/身份验证：`JWT_SECRET`、`INITIAL_PASSWORD` -- 存储：`DATA_DIR` -- 兼容节点行为：`ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- 可选存储基础覆盖（Linux/macOS 当 `DATA_DIR` 未设置时）：`XDG_CONFIG_HOME` -- 安全哈希：`API_KEY_SECRET`、`MACHINE_ID_SALT` -- 日志记录：`ENABLE_REQUEST_LOGS` -- 同步/云 URL：`NEXT_PUBLIC_BASE_URL`、`NEXT_PUBLIC_CLOUD_URL` -- 出站代理：`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY` 和小写变体 -- SOCKS5 功能标志：`ENABLE_SOCKS5_PROXY`、`NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- 平台/运行时帮助程序（不是特定于应用程序的配置）：`APPDATA`、`NODE_ENV`、`PORT`、`HOSTNAME` +- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD` +- Storage: `DATA_DIR` +- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME` +- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Logging: `ENABLE_REQUEST_LOGS` +- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants +- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` -## 已知的架构注释 +## Known Architectural Notes -1. `usageDb` 和 `localDb` 现在与旧文件迁移共享相同的基本目录策略 (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`)。 -2. `/api/v1/route.ts` 返回静态模型列表，不是 `/v1/models` 使用的主要模型源。 -3. 请求记录器在启用时写入完整的标头/正文；将日志目录视为敏感目录。 -4. 云行为取决于正确的 `NEXT_PUBLIC_BASE_URL` 和云端点可访问性。 -5. `open-sse/` 目录发布为 `@omniroute/open-sse` **npm 工作区包**。源代码通过 `@omniroute/open-sse/...` 导入它（由 Next.js `transpilePackages` 解析）。为了保持一致性，本文档中的文件路径仍使用目录名称 `open-sse/`。 -6. 仪表板中的图表使用 **Recharts**（基于 SVG）来实现可访问的交互式分析可视化（模型使用情况条形图、包含成功率的提供商细分表）。 -7. E2E 测试使用 **Playwright** (`tests/e2e/`)，通过 `npm run test:e2e` 运行。单元测试使用 **Node.js 测试运行程序** (`tests/unit/`)，通过 `npm run test:plan3` 运行。 `src/` 下的源代码是 **TypeScript** (`.ts`/`.tsx`)； `open-sse/` 工作区仍然是 JavaScript (`.js`)。 -8. 设置页面分为 5 个选项卡：安全、路由（6 种全局策略：先填充、循环、p2c、随机、最少使用、成本优化）、弹性（可编辑速率限制、断路器、策略）、AI（思考预算、系统提示、提示缓存）、高级（代理）。 +1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). -## 操作验证清单 +## Operational Verification Checklist -- 从源代码构建：`npm run build` -- 构建 Docker 镜像：`docker build -t omniroute .` -- 启动服务并验证： +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: - `GET /api/settings` - `GET /api/v1/models` -- 当 `PORT=20128` 时，CLI 目标基本 URL 应为 `http://:20128/v1` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/zh-CN/CODEBASE_DOCUMENTATION.md b/docs/i18n/zh-CN/CODEBASE_DOCUMENTATION.md index 46ed7a5d5b..303880c198 100644 --- a/docs/i18n/zh-CN/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/zh-CN/CODEBASE_DOCUMENTATION.md @@ -1,22 +1,22 @@ -🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) +# omniroute — Codebase Documentation -#omniroute — 代码库文档 +🌐 **Languages:** 🇺🇸 [English](CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](i18n/es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](i18n/fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](i18n/ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](i18n/in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](i18n/th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](i18n/ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](i18n/ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](i18n/vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](i18n/bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](i18n/he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](i18n/ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](i18n/ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](i18n/sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) > A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- -## 1. 什么是全向？ +## 1. What Is omniroute? -omniroute 是一个**代理路由器**，位于 AI 客户端（Claude CLI、Codex、Cursor IDE 等）和 AI 提供商（Anthropic、Google、OpenAI、AWS、GitHub 等）之间。它解决了一个大问题： +omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem: -> **不同的 AI 客户端使用不同的“语言”（API 格式），不同的 AI 提供商也期望不同的“语言”。**omniroute 自动在它们之间进行翻译。 +> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically. -可以将其想象为联合国的通用翻译器 - 任何代表都可以说任何语言，翻译器可以将其转换为任何其他代表。 +Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate. --- -## 2. 架构概述 +## 2. Architecture Overview ```mermaid graph LR @@ -61,7 +61,7 @@ graph LR H -.-> G ``` -### 核心原则：轴辐式翻译 +### Core Principle: Hub-and-Spoke Translation All format translation passes through **OpenAI format as the hub**: @@ -74,7 +74,7 @@ This means you only need **N translators** (one per format) instead of **N²** ( --- -## 3. 项目结构 +## 3. Project Structure ``` omniroute/ @@ -104,22 +104,22 @@ omniroute/ --- -## 4. 逐个模块细分 +## 4. Module-by-Module Breakdown -### 4.1 配置 (`open-sse/config/`) +### 4.1 Config (`open-sse/config/`) The **single source of truth** for all provider configuration. -| 文件 | 目的 | -| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` 对象，包含每个提供商的基本 URL、OAuth 凭据（默认）、标头和默认系统提示。还定义 `HTTP_STATUS`、`ERROR_TYPES`、`COOLDOWN_MS`、`BACKOFF_CONFIG` 和 `SKIP_PATTERNS`。 | -| `credentialLoader.ts` | 从 `data/provider-credentials.json` 加载外部凭据，并将它们合并到 `PROVIDERS` 中的硬编码默认值上。让秘密不受源代码控制，同时保持向后兼容性。 | -| `providerModels.ts` | 中央模型注册表：映射提供者别名 → 模型 ID。类似 `getModels()`、`getProviderByAlias()` 的函数。 | -| `codexInstructions.ts` | 系统指令注入到 Codex 请求中（编辑约束、沙箱规则、批准策略）。 | -| `defaultThinkingSignature.ts` | 克劳德和双子座模型的默认“思考”签名。 | -| `ollamaModels.ts` | 本地 Ollama 模型的架构定义（名称、大小、系列、量化）。 | +| File | Purpose | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. | +| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). | +| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. | +| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). | -#### 凭证加载流程 +#### Credential Loading Flow ```mermaid flowchart TD @@ -142,9 +142,9 @@ flowchart TD --- -### 4.2 执行者 (`open-sse/executors/`) +### 4.2 Executors (`open-sse/executors/`) -执行器使用**策略模式**封装**特定于提供者的逻辑**。每个执行器根据需要重写基本方法。 +Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed. ```mermaid classDiagram @@ -194,32 +194,32 @@ classDiagram BaseExecutor <|-- GithubExecutor ``` -| 执行人 | 供应商 | 重点专业 | -| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------ | -| `base.ts` | — | 抽象基础：URL 构建、标头、重试逻辑、凭证刷新 | -| `default.ts` | 克劳德、Gemini、OpenAI、GLM、Kimi、MiniMax | 标准提供商的通用 OAuth 令牌刷新 | -| `antigravity.ts` | 谷歌云代码 | 项目/会话 ID 生成、多 URL 回退、自定义重试错误消息解析（“2 小时 7 分 23 秒后重置”） | -| `cursor.ts` | 光标IDE | **最复杂**：SHA-256 校验和验证、Protobuf 请求编码、二进制 EventStream → SSE 响应解析 | -| `codex.ts` | OpenAI 法典 | 注入系统指令、管理思维水平、删除不支持的参数 | -| `gemini-cli.ts` | 谷歌 Gemini CLI | 自定义 URL 构建 (`streamGenerateContent`)、Google OAuth 令牌刷新 | -| `github.ts` | GitHub 副驾驶 | 双令牌系统（GitHub OAuth + Copilot 令牌），VSCode 标头模仿 | -| `kiro.ts` | AWS 代码耳语 | AWS EventStream 二进制解析、AMZN 事件框架、令牌估计 | -| `index.ts` | — | 工厂：地图提供者名称 → 执行器类，具有默认后备 | +| Executor | Provider | Key Specializations | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers | +| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing | +| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters | +| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh | +| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation | +| `index.ts` | — | Factory: maps provider name → executor class, with default fallback | --- -### 4.3 处理程序 (`open-sse/handlers/`) +### 4.3 Handlers (`open-sse/handlers/`) -**编排层** — 协调翻译、执行、流式传输和错误处理。 +The **orchestration layer** — coordinates translation, execution, streaming, and error handling. -| 文件 | 目的 | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **中央编排器**（约 600 行）。处理完整的请求生命周期：格式检测→转换→执行程序调度→流/非流响应→令牌刷新→错误处理→使用日志记录。 | -| `responsesHandler.ts` | OpenAI 响应 API 的适配器：转换响应格式 → 聊天完成 → 发送到 `chatCore` → 将 SSE 转换回响应格式。 | -| `embeddings.ts` | 嵌入生成处理程序：解析嵌入模型→提供者，分派到提供者 API，返回兼容 OpenAI 的嵌入响应。支持 6 个以上提供商。 | -| `imageGeneration.ts` | 图像生成处理程序：解析图像模型→提供程序，支持 OpenAI 兼容、Gemini-image（反重力）和后备（Nebius）模式。返回 base64 或 URL 图像。 | +| File | Purpose | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. | +| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. | +| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. | +| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. | -#### 请求生命周期 (chatCore.ts) +#### Request Lifecycle (chatCore.ts) ```mermaid sequenceDiagram @@ -258,28 +258,28 @@ sequenceDiagram --- -### 4.4 服务 (`open-sse/services/`) +### 4.4 Services (`open-sse/services/`) -支持处理程序和执行程序的业务逻辑。 +Business logic that supports the handlers and executors. -| 文件 | 目的 | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `provider.ts` | **格式检测** (`detectFormat`)：分析请求主体结构以识别 Claude/OpenAI/Gemini/Antigravity/Responses 格式（包括 Claude 的 `max_tokens` 启发式）。另外：URL 构建、标头构建、思考配置规范化。支持 `openai-compatible-*` 和 `anthropic-compatible-*` 动态提供程序。 | -| `model.ts` | 模型字符串解析 (`claude/model-name` → `{provider: "claude", model: "model-name"}`)、具有冲突检测的别名解析、输入清理（拒绝路径遍历/控制字符）以及具有异步别名 getter 支持的模型信息解析。 | -| `accountFallback.ts` | 速率限制处理：指数退避（1 秒 → 2 秒 → 4 秒 → 最大 2 分钟）、帐户冷却管理、错误分类（哪些错误触发回退，哪些错误不触发）。 | -| `tokenRefresh.ts` | **每个提供商**的 OAuth 令牌刷新：Google（Gemini、Antigravity）、Claude、Codex、Qwen、iFlow、GitHub（OAuth + Copilot 双令牌）、Kiro（AWS SSO OIDC + 社交身份验证）。包括正在进行的承诺重复数据删除缓存和指数退避重试。 | -| `combo.ts` | **组合模型**：后备模型链。如果模型 A 因符合后备条件的错误而失败，请尝试模型 B，然后是模型 C，等等。返回实际的上游状态代码。 | -| `usage.ts` | 从提供商 API 获取配额/使用数据（GitHub Copilot 配额、Antigravity 模型配额、Codex 速率限制、Kiro 使用细分、Claude 设置）。 | -| `accountSelector.ts` | 具有评分算法的智能帐户选择：考虑优先级、健康状态、循环位置和冷却状态，为每个请求选择最佳帐户。 | -| `contextManager.ts` | 请求上下文生命周期管理：使用元数据（请求 ID、时间戳、提供程序信息）创建和跟踪每个请求上下文对象，以进行调试和日志记录。 | -| `ipFilter.ts` | 基于IP的访问控制：支持白名单和黑名单模式。在处理 API 请求之前根据配置的规则验证客户端 IP。 | -| `sessionManager.ts` | 使用客户端指纹进行会话跟踪：使用散列客户端标识符跟踪活动会话、监视请求计数并提供会话指标。 | -| `signatureCache.ts` | 基于请求签名的重复数据删除缓存：通过缓存最近的请求签名并在时间窗口内返回相同请求的缓存响应来防止重复请求。 | -| `systemPrompt.ts` | 全局系统提示注入：在所有请求之前或附加一个可配置的系统提示，并进行每个提供商的兼容性处理。 | -| `thinkingBudget.ts` | 推理令牌预算管理：支持直通、自动（条带思维配置）、自定义（固定预算）和自适应（复杂度缩放）模式来控制思维/推理令牌。 | -| `wildcardRouter.ts` | 通配符模型模式路由：根据可用性和优先级将通配符模式（例如 `*/claude-*`）解析为具体的提供者/模型对。 | +| File | Purpose | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. | +| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. | +| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). | +| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. | +| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. | +| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). | +| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. | +| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. | +| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. | +| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. | +| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. | +| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. | +| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. | +| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. | -#### 令牌刷新重复数据删除 +#### Token Refresh Deduplication ```mermaid sequenceDiagram @@ -300,7 +300,7 @@ sequenceDiagram Cache->>Cache: Delete cache entry ``` -#### 帐户回退状态机 +#### Account Fallback State Machine ```mermaid stateDiagram-v2 @@ -325,7 +325,7 @@ stateDiagram-v2 } ``` -#### 组合模型链 +#### Combo Model Chain ```mermaid flowchart LR @@ -344,11 +344,11 @@ flowchart LR --- -### 4.5 翻译器 (`open-sse/translator/`) +### 4.5 Translator (`open-sse/translator/`) -使用自注册插件系统的 **格式翻译引擎**。 +The **format translation engine** using a self-registering plugin system. -#### 架构 +#### Architecture ```mermaid graph TD @@ -374,15 +374,15 @@ graph TD end ``` -| 目录 | 文件 | 描述 | -| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 位译员 | 在格式之间转换请求正文。每个文件在导入时通过 `register(from, to, fn)` 自行注册。 | -| `response/` | 7 名翻译 | 在格式之间转换流响应块。处理 SSE 事件类型、思维块、工具调用。 | -| `helpers/` | 6 帮手 | 共享实用程序：`claudeHelper`（系统提示提取、思考配置）、`geminiHelper`（部分/内容映射）、`openaiHelper`（格式过滤）、`toolCallHelper`（ID生成、缺失响应注入）、`maxTokensHelper`、`responsesApiHelper`。 | -| `index.ts` | — | 翻译引擎：`translateRequest()`、`translateResponse()`、状态管理、注册表。 | -| `formats.ts` | — | 格式常量：`OPENAI`、`CLAUDE`、`GEMINI`、`ANTIGRAVITY`、`KIRO`、`CURSOR`、`OPENAI_RESPONSES`。 | +| Directory | Files | Description | +| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. | +| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. | +| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. | +| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | -#### 关键设计：自注册插件 +#### Key Design: Self-Registering Plugins ```javascript // Each translator file calls register() on import: @@ -395,19 +395,19 @@ import "./request/claude-to-openai.js"; // ← self-registers --- -### 4.6 实用程序 (`open-sse/utils/`) +### 4.6 Utils (`open-sse/utils/`) -| 文件 | 目的 | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | 错误响应构建（OpenAI 兼容格式）、上游错误解析、从错误消息中提取反重力重试时间、SSE 错误流。 | -| `stream.ts` | **SSE Transform Stream** — 核心流管道。两种模式：`TRANSLATE`（完整格式翻译）和`PASSTHROUGH`（规范化+提取使用）。处理块缓冲、使用情况估计、内容长度跟踪。每个流编码器/解码器实例避免共享状态。 | -| `streamHelpers.ts` | 低级 SSE 实用程序：`parseSSELine`（空白容忍）、`hasValuableContent`（过滤 OpenAI/Claude/Gemini 的空块）、`fixInvalidId`、`formatSSE`（具有 `perf_metrics` 清理功能的格式感知 SSE 序列化）。 | -| `usageTracking.ts` | 从任何格式（Claude/OpenAI/Gemini/Responses）提取令牌使用情况，使用单独的工具/消息字符/令牌比率进行估计，缓冲区添加（2000 个令牌安全裕度），特定于格式的字段过滤，使用 ANSI 颜色的控制台日志记录。 | -| `requestLogger.ts` | 基于文件的请求日志记录（通过 `ENABLE_REQUEST_LOGS=true` 选择加入）。创建包含编号文件的会话文件夹：`1_req_client.json` → `7_res_client.txt`。所有 I/O 都是异步的（即发即弃）。屏蔽敏感标头。 | -| `bypassHandler.ts` | 拦截来自 Claude CLI 的特定模式（标题提取、预热、计数）并返回虚假响应，而无需调用任何提供者。支持流式传输和非流式传输。有意限制为 Claude CLI 范围。 | -| `networkProxy.ts` | 优先解析给定提供程序的出站代理 URL：提供程序特定的配置 → 全局配置 → 环境变量 (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`)。支持 `NO_PROXY` 排除。缓存配置 30 秒。 | +| File | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. | +| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. | +| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). | +| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. | +| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. | +| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. | +| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. | -#### SSE 流媒体管道 +#### SSE Streaming Pipeline ```mermaid flowchart TD @@ -429,7 +429,7 @@ flowchart TD style M fill:#9f9,stroke:#333 ``` -#### 请求记录器会话结构 +#### Request Logger Session Structure ``` logs/ @@ -447,109 +447,109 @@ logs/ --- -### 4.7 应用层 (`src/`) +### 4.7 Application Layer (`src/`) -| 目录 | 目的 | -| ------------- | -------------------------------------------------------- | -| `src/app/` | Web UI、API 路由、Express 中间件、OAuth 回调处理程序 | -| `src/lib/` | 数据库访问（`localDb.ts`、`usageDb.ts`）、身份验证、共享 | -| `src/mitm/` | 用于拦截提供商流量的中间人代理实用程序 | -| `src/models/` | 数据库模型定义 | -| `src/shared/` | open-sse 函数（提供程序、流、错误等）的包装器 | -| `src/sse/` | 将 open-sse 库连接到 Express 路由的 SSE 端点处理程序 | -| `src/store/` | 应用状态管理 | +| Directory | Purpose | +| ------------- | ---------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers | +| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared | +| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic | +| `src/models/` | Database model definitions | +| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) | +| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes | +| `src/store/` | Application state management | -#### 值得注意的 API 路由 +#### Notable API Routes -| 路线 | 方法 | 目的 | -| --------------------------------------------- | -------------- | ------------------------------------------------------------ | -| `/api/provider-models` | 获取/发布/删除 | 针对每个提供商的自定义模型的 CRUD | -| `/api/models/catalog` | 获取 | 按提供商分组的所有模型（聊天、嵌入、图像、自定义）的聚合目录 | -| `/api/settings/proxy` | 获取/放置/删除 | 分层出站代理配置 (`global/providers/combos/keys`) | -| `/api/settings/proxy/test` | 发布 | 验证代理连接并返回公共 IP/延迟 | -| `/v1/providers/[provider]/chat/completions` | 发布 | 通过模型验证完成每个提供商的专用聊天 | -| `/v1/providers/[provider]/embeddings` | 发布 | 具有模型验证功能的专用每个提供商嵌入 | -| `/v1/providers/[provider]/images/generations` | 发布 | 通过模型验证生成专用的每个提供商图像 | -| `/api/settings/ip-filter` | 获取/放置 | IP 允许列表/阻止列表管理 | -| `/api/settings/thinking-budget` | 获取/放置 | 推理代币预算配置（直通/自动/自定义/自适应） | -| `/api/settings/system-prompt` | 获取/放置 | 所有请求的全局系统提示注入 | -| `/api/sessions` | 获取 | 活动会话跟踪和指标 | -| `/api/rate-limits` | 获取 | 每个帐户的速率限制状态 | +| Route | Methods | Purpose | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider | +| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency | +| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation | +| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation | +| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests | +| `/api/sessions` | GET | Active session tracking and metrics | +| `/api/rate-limits` | GET | Per-account rate limit status | --- -## 5. 关键设计模式 +## 5. Key Design Patterns -### 5.1 轴辐式翻译 +### 5.1 Hub-and-Spoke Translation -所有格式均通过 **OpenAI 格式作为中心**进行转换。添加新的提供者只需要编写**一对**翻译器（到/来自 OpenAI），而不是 N 对。 +All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs. -### 5.2 执行者策略模式 +### 5.2 Executor Strategy Pattern -每个提供者都有一个继承自 `BaseExecutor` 的专用执行器类。 `executors/index.ts` 中的工厂在运行时选择正确的一个。 +Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime. -### 5.3 自注册插件系统 +### 5.3 Self-Registering Plugin System -翻译器模块在导入时通过 `register()` 注册自身。添加新翻译器只是创建一个文件并将其导入。 +Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it. -### 5.4 具有指数退避的账户回退 +### 5.4 Account Fallback with Exponential Backoff -当提供者返回 429/401/500 时，系统可以切换到下一个帐户，应用指数冷却时间（1 秒 → 2 秒 → 4 秒 → 最长 2 分钟）。 +When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min). -### 5.5 组合模型链 +### 5.5 Combo Model Chains -“组合”将多个 `provider/model` 字符串组合在一起。如果第一个失败，则自动回退到下一个。 +A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically. -### 5.6 有状态流式翻译 +### 5.6 Stateful Streaming Translation -响应翻译通过 `initState()` 机制维护跨 SSE 块的状态（思维块跟踪、工具调用积累、内容块索引）。 +Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism. -### 5.7 使用安全缓冲区 +### 5.7 Usage Safety Buffer -在报告的使用情况中添加了 2000 个令牌缓冲区，以防止客户端由于系统提示和格式转换的开销而达到上下文窗口限制。 +A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation. --- -## 6. 支持的格式 +## 6. Supported Formats -| 格式 | 方向 | 标识符 | -| --------------- | --------- | ------------------ | -| OpenAI 聊天完成 | 来源+目标 | `openai` | -| OpenAI 响应 API | 来源+目标 | `openai-responses` | -| 人类克劳德 | 来源+目标 | `claude` | -| 谷歌双子座 | 来源+目标 | `gemini` | -| 谷歌 Gemini CLI | 仅目标 | `gemini-cli` | -| 反重力 | 来源+目标 | `antigravity` | -| AWS 基罗 | AWS仅目标 | `kiro` | -| 光标 | 仅目标 | `cursor` | +| Format | Direction | Identifier | +| ----------------------- | --------------- | ------------------ | +| OpenAI Chat Completions | source + target | `openai` | +| OpenAI Responses API | source + target | `openai-responses` | +| Anthropic Claude | source + target | `claude` | +| Google Gemini | source + target | `gemini` | +| Google Gemini CLI | target only | `gemini-cli` | +| Antigravity | source + target | `antigravity` | +| AWS Kiro | target only | `kiro` | +| Cursor | target only | `cursor` | --- -## 7. 支持的提供商 +## 7. Supported Providers -| 供应商 | 认证方式 | 执行人 | 要点 | -| ------------------------ | -------------------- | --------- | --------------------------------- | -| 人类克劳德 | API 密钥或 OAuth | 默认 | 使用 `x-api-key` 标头 | -| 谷歌双子座 | API 密钥或 OAuth | 默认 | 使用 `x-goog-api-key` 标头 | -| 谷歌 Gemini CLI | OAuth | GeminiCLI | 使用 `streamGenerateContent` 端点 | -| 反重力 | OAuth | 反重力 | 多 URL 回退、自定义重试解析 | -| 开放人工智能 | API 密钥 | 默认 | 标准持有者身份验证 | -| 法典 | OAuth | 法典 | 注入系统指令，管理思维 | -| GitHub 副驾驶 | OAuth + Copilot 令牌 | GitHub | 双令牌，VSCode 标头模仿 | -| 基罗 (AWS) | AWS SSO OIDC 或社交 | 基罗 | 二进制EventStream解析 | -| 光标IDE | 校验和验证 | 光标 | Protobuf 编码、SHA-256 校验和 | -| 奎文 | OAuth | 默认 | 标准授权 | -| iFlow | OAuth（基本 + 承载） | 默认 | 双重身份验证标头 | -| 开放路由器 | API 密钥 | 默认 | 标准持有者身份验证 | -| GLM、Kimi、MiniMax | API 密钥 | 默认 | 克劳德兼容，使用 `x-api-key` | -| `openai-compatible-*` | API 密钥 | 默认 | 动态：任何 OpenAI 兼容端点 | -| `anthropic-compatible-*` | API 密钥 | 默认 | 动态：任何与 Claude 兼容的端点 | +| Provider | Auth Method | Executor | Key Notes | +| ------------------------ | ---------------------- | ----------- | --------------------------------------------- | +| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header | +| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header | +| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint | +| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing | +| OpenAI | API key | Default | Standard Bearer auth | +| Codex | OAuth | Codex | Injects system instructions, manages thinking | +| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking | +| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing | +| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums | +| Qwen | OAuth | Default | Standard auth | +| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header | +| OpenRouter | API key | Default | Standard Bearer auth | +| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` | +| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint | +| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint | --- -## 8. 数据流总结 +## 8. Data Flow Summary -### 流媒体请求 +### Streaming Request ```mermaid flowchart LR @@ -566,7 +566,7 @@ flowchart LR K --> L["logUsage()\nsaveRequestUsage()"] ``` -### 非流式请求 +### Non-Streaming Request ```mermaid flowchart LR @@ -577,7 +577,7 @@ flowchart LR E --> F["Return JSON\nresponse"] ``` -### 旁路流程（Claude CLI） +### Bypass Flow (Claude CLI) ```mermaid flowchart LR diff --git a/docs/i18n/zh-CN/FEATURES.md b/docs/i18n/zh-CN/FEATURES.md index 0315055a59..82cc73b67b 100644 --- a/docs/i18n/zh-CN/FEATURES.md +++ b/docs/i18n/zh-CN/FEATURES.md @@ -1,77 +1,142 @@ -# OmniRoute — 仪表板功能库 +# OmniRoute — Dashboard Features Gallery -🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) +🌐 **Languages:** 🇺🇸 [English](FEATURES.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/FEATURES.md) | 🇪🇸 [Español](i18n/es/FEATURES.md) | 🇫🇷 [Français](i18n/fr/FEATURES.md) | 🇮🇹 [Italiano](i18n/it/FEATURES.md) | 🇷🇺 [Русский](i18n/ru/FEATURES.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](i18n/de/FEATURES.md) | 🇮🇳 [हिन्दी](i18n/in/FEATURES.md) | 🇹🇭 [ไทย](i18n/th/FEATURES.md) | 🇺🇦 [Українська](i18n/uk-UA/FEATURES.md) | 🇸🇦 [العربية](i18n/ar/FEATURES.md) | 🇯🇵 [日本語](i18n/ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](i18n/vi/FEATURES.md) | 🇧🇬 [Български](i18n/bg/FEATURES.md) | 🇩🇰 [Dansk](i18n/da/FEATURES.md) | 🇫🇮 [Suomi](i18n/fi/FEATURES.md) | 🇮🇱 [עברית](i18n/he/FEATURES.md) | 🇭🇺 [Magyar](i18n/hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/FEATURES.md) | 🇰🇷 [한국어](i18n/ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/FEATURES.md) | 🇳🇱 [Nederlands](i18n/nl/FEATURES.md) | 🇳🇴 [Norsk](i18n/no/FEATURES.md) | 🇵🇹 [Português (Portugal)](i18n/pt/FEATURES.md) | 🇷🇴 [Română](i18n/ro/FEATURES.md) | 🇵🇱 [Polski](i18n/pl/FEATURES.md) | 🇸🇰 [Slovenčina](i18n/sk/FEATURES.md) | 🇸🇪 [Svenska](i18n/sv/FEATURES.md) | 🇵🇭 [Filipino](i18n/phi/FEATURES.md) -OmniRoute 仪表板每个部分的视觉指南。 +Visual guide to every section of the OmniRoute dashboard. --- -## 🔌 提供商 +## 🔌 Providers -管理 AI 提供商连接：OAuth 提供商（Claude Code、Codex、Gemini CLI）、API 密钥提供商（Groq、DeepSeek、OpenRouter）和免费提供商（iFlow、Qwen、Kiro）。 +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). ![Providers Dashboard](screenshots/01-providers.png) --- -## 🎨 组合 +## 🎨 Combos -使用 6 种策略创建模型路由组合：填充优先、循环、二选一、随机、最少使用和成本优化。每个组合都会链接多个模型并自动回退。 +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## 📊 分析 +## 📊 Analytics -全面的使用分析，包括代币消耗、成本估算、活动热图、每周分布图和每个提供商的细分。 +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## 🏥 系统健康状况 +## 🏥 System Health -实时监控：正常运行时间、内存、版本、延迟百分位数 (p50/p95/p99)、缓存统计数据和提供商断路器状态。 +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## 🔧 翻译游乐场 +## 🔧 Translator Playground -用于调试 API 翻译的四种模式：**Playground**（格式转换器）、**Chat Tester**（实时请求）、**Test Bench**（批量测试）和 **Live Monitor**（实时流）。 +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ⚙️ 设置 +## 🎮 Model Playground _(v2.0.9+)_ -常规设置、系统存储、备份管理（导出/导入数据库）、外观（深色/浅色模式）、安全性（包括 API 端点保护和自定义提供程序阻止）、路由、弹性和高级配置。 +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. + +--- + +## 🎨 Themes _(v2.0.5+)_ + +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. + +--- + +## ⚙️ Settings + +Comprehensive settings panel with tabs: + +- **General** — System storage, backup management (export/import database) +- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility +- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** — Model aliases, background task degradation +- **Resilience** — Rate limit persistence, circuit breaker tuning +- **Advanced** — Configuration overrides ![Settings Dashboard](screenshots/06-settings.png) --- -## 🔧 CLI 工具 +## 🔧 CLI Tools -一键配置AI编码工具：Claude Code、Codex CLI、Gemini CLI、OpenClaw、Kilo Code、Antigravity。 +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## 📝 请求日志 +## 🤖 CLI Agents _(v2.0.11+)_ -实时请求记录，并按提供商、模型、帐户和 API 密钥进行过滤。显示状态代码、令牌使用情况、延迟和响应详细信息。 +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: + +- **Installation status** — Installed / Not Found with version detection +- **Protocol badges** — stdio, HTTP, etc. +- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP + +--- + +## 🖼️ Media _(v2.0.3+)_ + +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. + +--- + +## 📝 Request Logs + +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## 🌐 API 端点 +## 🌐 API Endpoint -您的统一 API 端点具有功能细分：聊天完成、嵌入、图像生成、重新排名、音频转录和注册 API 密钥。 +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) + +--- + +## 🔑 API Key Management + +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. + +--- + +## 📋 Audit Log + +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. + +--- + +## 🖥️ Desktop Application + +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. + +Key features: + +- Server readiness polling (no blank screen on cold start) +- System tray with port management +- Content Security Policy +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) + +📖 See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/zh-CN/TROUBLESHOOTING.md b/docs/i18n/zh-CN/TROUBLESHOOTING.md index 32d2985402..120092d63c 100644 --- a/docs/i18n/zh-CN/TROUBLESHOOTING.md +++ b/docs/i18n/zh-CN/TROUBLESHOOTING.md @@ -1,84 +1,87 @@ -# 故障排除 +# Troubleshooting -🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) +🌐 **Languages:** 🇺🇸 [English](TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](i18n/es/TROUBLESHOOTING.md) | 🇫🇷 [Français](i18n/fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](i18n/it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](i18n/ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](i18n/de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](i18n/in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](i18n/th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](i18n/uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](i18n/ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](i18n/ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](i18n/vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](i18n/bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](i18n/da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](i18n/fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](i18n/he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](i18n/hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](i18n/ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](i18n/nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](i18n/no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](i18n/pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](i18n/ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](i18n/pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](i18n/sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](i18n/sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](i18n/phi/TROUBLESHOOTING.md) -OmniRoute 的常见问题和解决方案。 +Common problems and solutions for OmniRoute. --- -## 快速修复 +## Quick Fixes -| 问题 | 解决方案 | -| ---------------------- | ------------------------------------------------------------------ | -| 首次登录无法使用 | 检查 `.env` 中的 `INITIAL_PASSWORD`（默认：`123456`） | -| 仪表板在错误端口上打开 | 设置 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| `logs/` 下没有请求日志 | 设置 `ENABLE_REQUEST_LOGS=true` | -| EACCES：权限被拒绝 | 设置 `DATA_DIR=/path/to/writable/dir` 来覆盖 `~/.omniroute` | -| 路由策略未保存 | 更新至 v1.4.11+（Zod 架构修复设置持久性） | +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | --- -## 提供商问题 +## Provider Issues -###“语言模型未提供消息” +### "Language model did not provide messages" -**原因：** 提供商配额已用完。 +**Cause:** Provider quota exhausted. -**修复：** +**Fix:** -1.检查仪表板配额跟踪器2. 使用具有后备层的组合3.切换到更便宜/免费的套餐 +1. Check dashboard quota tracker +2. Use a combo with fallback tiers +3. Switch to cheaper/free tier -### 速率限制 +### Rate Limiting -**原因：** 订阅配额已用完。 +**Cause:** Subscription quota exhausted. -**修复：** +**Fix:** -- 添加后备：`cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- 使用 GLM/MiniMax 作为廉价备份 +- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax as cheap backup -### OAuth 令牌已过期 +### OAuth Token Expired -OmniRoute 自动刷新令牌。如果问题仍然存在： +OmniRoute auto-refreshes tokens. If issues persist: -1. 仪表板 → 提供商 → 重新连接 2.删除并重新添加提供商连接 +1. Dashboard → Provider → Reconnect +2. Delete and re-add the provider connection --- -## 云问题 +## Cloud Issues -### 云同步错误 +### Cloud Sync Errors -1. 验证 `BASE_URL` 指向您正在运行的实例（例如 `http://localhost:20128`） -2. 验证 `CLOUD_URL` 指向您的云端点（例如 `https://omniroute.dev`） -3. 保持 `NEXT_PUBLIC_*` 值与服务器端值一致 +1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`) +2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`) +3. Keep `NEXT_PUBLIC_*` values aligned with server-side values -### 云 `stream=false` 返回 500 +### Cloud `stream=false` Returns 500 -**症状：** 云端点上的 `Unexpected token 'd'...` 用于非流式调用。 +**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls. -**原因：** 上游返回 SSE 负载，而客户端需要 JSON。 +**Cause:** Upstream returns SSE payload while client expects JSON. -**解决方法：** 使用 `stream=true` 进行云直接调用。本地运行时包括 SSE→JSON 回退。 +**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback. -### 云显示已连接但“API 密钥无效” +### Cloud Says Connected but "Invalid API key" -1. 从本地仪表板创建新密钥 (`/api/keys`) -2. 运行云同步：启用云→立即同步 -3. 旧的/未同步的密钥仍然可以在云上返回 `401` +1. Create a fresh key from local dashboard (`/api/keys`) +2. Run cloud sync: Enable Cloud → Sync Now +3. Old/non-synced keys can still return `401` on cloud --- -## Docker 问题 +## Docker Issues -### CLI 工具显示未安装 +### CLI Tool Shows Not Installed -1. 检查运行时字段：`curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. 对于便携模式：使用映像目标 `runner-cli`（捆绑的 CLI） -3. 对于主机挂载模式：设置`CLI_EXTRA_PATHS`并挂载主机bin目录为只读 -4. 如果 `installed=true` 和 `runnable=false`：找到二进制文件，但运行状况检查失败 +1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. For portable mode: use image target `runner-cli` (bundled CLIs) +3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only +4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck -### 快速运行时验证 +### Quick Runtime Validation ```bash curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}' @@ -88,24 +91,24 @@ curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed, --- -## 成本问题 +## Cost Issues -### 高成本 +### High Costs -1. 在 Dashboard → 使用情况中查看使用情况统计数据 -2. 将主模型切换为GLM/MiniMax -3. 使用免费层（Gemini CLI、iFlow）执行非关键任务 -4. 设置每个 API 密钥的成本预算：仪表板 → API 密钥 → 预算 +1. Check usage stats in Dashboard → Usage +2. Switch primary model to GLM/MiniMax +3. Use free tier (Gemini CLI, iFlow) for non-critical tasks +4. Set cost budgets per API key: Dashboard → API Keys → Budget --- -## 调试 +## Debugging -### 启用请求日志 +### Enable Request Logs -在 `.env` 文件中设置 `ENABLE_REQUEST_LOGS=true`。日志显示在 `logs/` 目录下。 +Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory. -### 检查提供商的健康状况 +### Check Provider Health ```bash # Health dashboard @@ -115,102 +118,137 @@ http://localhost:20128/dashboard/health curl http://localhost:20128/api/monitoring/health ``` -### 运行时存储 +### Runtime Storage -- 主要状态：`${DATA_DIR}/db.json`（提供程序、组合、别名、键、设置） -- 用法：`${DATA_DIR}/usage.json`、`${DATA_DIR}/log.txt`、`${DATA_DIR}/call_logs/` -- 请求日志：`/logs/...`（当 `ENABLE_REQUEST_LOGS=true` 时） +- Main state: `${DATA_DIR}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) --- -## 断路器问题 +## Circuit Breaker Issues -### 提供程序陷入打开状态 +### Provider stuck in OPEN state -当提供商的断路器打开时，请求将被阻止，直到冷却时间到期。 +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. -**修复：** +**Fix:** -1. 转到 **仪表板 → 设置 → 弹性** -2. 检查受影响提供商的断路器卡 -3. 单击“**全部重置**”以清除所有断路器，或等待冷却时间到期 -4. 重置前验证提供商是否确实可用 +1. Go to **Dashboard → Settings → Resilience** +2. Check the circuit breaker card for the affected provider +3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire +4. Verify the provider is actually available before resetting -### 提供商不断使断路器跳闸 +### Provider keeps tripping the circuit breaker -如果提供者重复进入 OPEN 状态： +If a provider repeatedly enters OPEN state: -1. 检查 **仪表板 → 运行状况 → 提供商运行状况** 以了解故障模式 -2. 转到 **设置 → 恢复能力 → 提供商配置文件** 并增加失败阈值 -3. 检查提供商是否更改了 API 限制或需要重新身份验证 -4. 检查延迟遥测 — 高延迟可能会导致基于超时的故障 +1. Check **Dashboard → Health → Provider Health** for the failure pattern +2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold +3. Check if the provider has changed API limits or requires re-authentication +4. Review latency telemetry — high latency may cause timeout-based failures --- -## 音频转录问题 +## Audio Transcription Issues -### “不支持的型号”错误 +### "Unsupported model" error -- 确保您使用正确的前缀：`deepgram/nova-3` 或 `assemblyai/best` -- 验证提供商是否已在 **仪表板 → 提供商** 中连接 +- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best` +- Verify the provider is connected in **Dashboard → Providers** -### 转录返回空或失败 +### Transcription returns empty or fails -- 检查支持的音频格式：`mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm` -- 验证文件大小是否在提供商限制内（通常< 25MB） -- 检查提供商卡中提供商 API 密钥的有效性 +- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verify file size is within provider limits (typically < 25MB) +- Check provider API key validity in the provider card --- -## 翻译器调试 +## Translator Debugging -使用 **Dashboard → Translator** 调试格式转换问题： +Use **Dashboard → Translator** to debug format translation issues: -| 模式 | 何时使用 | -| -------------- | ------------------------------------------------------ | -| **游乐场** | 并排比较输入/输出格式 — 粘贴失败的请求以查看其如何翻译 | -| **聊天测试仪** | 发送实时消息并检查完整的请求/响应负载（包括标头） | -| **测试台** | 跨格式组合运行批量测试以查找哪些翻译被破坏 | -| **实时监控** | 观看实时请求流以捕获间歇性翻译问题 | +| Mode | When to Use | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates | +| **Chat Tester** | Send live messages and inspect the full request/response payload including headers | +| **Test Bench** | Run batch tests across format combinations to find which translations are broken | +| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues | -### 常见格式问题 +### Common format issues -- **思维标签未出现** — 检查目标提供商是否支持思维以及思维预算设置 -- **工具调用丢失** — 某些格式翻译可能会删除不支持的字段；在 Playground 模式下验证 -- **系统提示缺失** — Claude 和 Gemini 处理系统提示的方式不同；检查翻译输出 -- **SDK 返回原始字符串而不是对象** — 在 v1.1.0 中修复：响应清理程序现在会删除导致 OpenAI SDK Pydantic 验证失败的非标准字段（`x_groq`、`usage_breakdown` 等） -- **GLM/ERNIE 拒绝 `system` 角色** — 在 v1.1.0 中修复：角色标准化器自动将系统消息合并到不兼容模型的用户消息中 -- **`developer` 角色无法识别** — v1.1.0 中已修复：对于非 OpenAI 提供商，自动转换为 `system` -- **`json_schema` 不适用于 Gemini** — 在 v1.1.0 中修复：`response_format` 现在转换为 Gemini 的 `responseMimeType` + `responseSchema` +- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting +- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode +- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output +- **SDK returns raw string instead of object** — Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** — Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** — Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** — Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` --- -## 弹性设置 +## Resilience Settings -### 自动速率限制未触发 +### Auto rate-limit not triggering -- 自动速率限制仅适用于 API 密钥提供商（不适用于 OAuth/订阅） -- 验证**设置 → 弹性 → 提供商配置文件** 已启用自动速率限制 -- 检查提供商是否返回 `429` 状态代码或 `Retry-After` 标头 +- Auto rate-limit only applies to API key providers (not OAuth/subscription) +- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled +- Check if the provider returns `429` status codes or `Retry-After` headers -### 调整指数退避 +### Tuning exponential backoff -提供商配置文件支持以下设置： +Provider profiles support these settings: -- **基本延迟** — 第一次失败后的初始等待时间（默认值：1 秒） -- **最大延迟** — 最大等待时间上限（默认值：30 秒） -- **乘数** — 每次连续失败增加多少延迟（默认值：2x） +- **Base delay** — Initial wait time after first failure (default: 1s) +- **Max delay** — Maximum wait time cap (default: 30s) +- **Multiplier** — How much to increase delay per consecutive failure (default: 2x) -### 抗雷兽群 +### Anti-thundering herd -当许多并发请求到达速率受限的提供程序时，OmniRoute 使用互斥锁 + 自动速率限制来序列化请求并防止级联故障。对于 API 密钥提供者来说，这是自动的。 +When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers. --- -## 仍然卡住吗？ +## Optional RAG / LLM failure taxonomy (16 problems) -- **GitHub 问题**：[github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **架构**：请参阅 [link](ARCHITECTURE.md) 了解内部详细信息 -- **API 参考**：请参阅 [link](API_REFERENCE.md) 了解所有端点 -- **健康仪表板**：检查**仪表板→健康**以获取实时系统状态 -- **翻译器**：使用**仪表板→翻译器**来调试格式问题 +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` … `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard → Health** for real-time system status +- **Translator**: Use **Dashboard → Translator** to debug format issues diff --git a/docs/i18n/zh-CN/USER_GUIDE.md b/docs/i18n/zh-CN/USER_GUIDE.md index 6e1f82628d..5a043224df 100644 --- a/docs/i18n/zh-CN/USER_GUIDE.md +++ b/docs/i18n/zh-CN/USER_GUIDE.md @@ -1,12 +1,12 @@ -# 用户指南 +# User Guide -🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) +🌐 **Languages:** 🇺🇸 [English](USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](i18n/es/USER_GUIDE.md) | 🇫🇷 [Français](i18n/fr/USER_GUIDE.md) | 🇮🇹 [Italiano](i18n/it/USER_GUIDE.md) | 🇷🇺 [Русский](i18n/ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](i18n/de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](i18n/in/USER_GUIDE.md) | 🇹🇭 [ไทย](i18n/th/USER_GUIDE.md) | 🇺🇦 [Українська](i18n/uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](i18n/ar/USER_GUIDE.md) | 🇯🇵 [日本語](i18n/ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/USER_GUIDE.md) | 🇧🇬 [Български](i18n/bg/USER_GUIDE.md) | 🇩🇰 [Dansk](i18n/da/USER_GUIDE.md) | 🇫🇮 [Suomi](i18n/fi/USER_GUIDE.md) | 🇮🇱 [עברית](i18n/he/USER_GUIDE.md) | 🇭🇺 [Magyar](i18n/hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | 🇰🇷 [한국어](i18n/ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](i18n/nl/USER_GUIDE.md) | 🇳🇴 [Norsk](i18n/no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/USER_GUIDE.md) | 🇷🇴 [Română](i18n/ro/USER_GUIDE.md) | 🇵🇱 [Polski](i18n/pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](i18n/sk/USER_GUIDE.md) | 🇸🇪 [Svenska](i18n/sv/USER_GUIDE.md) | 🇵🇭 [Filipino](i18n/phi/USER_GUIDE.md) -有关配置提供程序、创建组合、集成 CLI 工具和部署 OmniRoute 的完整指南。 +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. --- -## 目录 +## Table of Contents - [Pricing at a Glance](#-pricing-at-a-glance) - [Use Cases](#-use-cases) @@ -18,40 +18,40 @@ --- -## 💰 定价一览 +## 💰 Pricing at a Glance -| 等级 | 供应商 | 成本 | 配额重置 | 最适合 | -| --------------- | ---------------------- | ------------------- | --------------- | -------------- | -| **💳 订阅** | 克劳德代码（专业版） | $20/月 | 5 小时+ 每周 | 已经订阅 | -| | Codex（增强版/专业版） | $20-200/月 | 5 小时+ 每周 | OpenAI 用户 | -| | 双子座 CLI | **免费** | 180K/月 + 1K/天 | 每个人！ | -| | GitHub 副驾驶 | $10-19/月 | 每月 | GitHub 用户 | -| **🔑 API 密钥** | 深度搜索 | 按使用付费 | 无 | 廉价推理 | -| | 格罗克 | 按使用付费 | 无 | 超快速推理 | -| | xAI (Grok) | 按使用付费 | 无 | Grok 4 推理 | -| | 米斯特拉尔 | 按使用付费 | 无 | 欧盟主办的模型 | -| | 困惑 | 按使用付费 | 无 | 搜索增强 | -| | 一起人工智能 | 按使用付费 | 无 | 开源模型 | -| | 烟花人工智能 | 按使用付费 | 无 | 快速通量图像 | -| | 大脑 | 按使用付费 | 无 | 晶圆级速度 | -| | 连贯 | 按使用付费 | 无 | 命令 R+ RAG | -| | NVIDIA NIM | 按使用付费 | 无 | 企业典范 | -| **💰便宜** | GLM-4.7 | 0.6 美元/100 万美元 | 每日上午 10 点 | 预算备份 | -| | 迷你最大M2.1 | 0.2 美元/100 万美元 | 5小时滚动 | 最便宜的选择 | -| | 基米K2 | 每月 9 美元的公寓 | 10M 代币/月 | 可预测的成本 | -| **🆓 免费** | iFlow | 0 美元 | 无限 | 8 款免费 | -| | 奎文 | 0 美元 | 无限 | 3 款免费 | -| | 基罗 | 0 美元 | 无限 | 克劳德自由 | +| Tier | Provider | Cost | Quota Reset | Best For | +| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | +| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | +| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | +| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! | +| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | +| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning | +| | Groq | Pay per use | None | Ultra-fast inference | +| | xAI (Grok) | Pay per use | None | Grok 4 reasoning | +| | Mistral | Pay per use | None | EU-hosted models | +| | Perplexity | Pay per use | None | Search-augmented | +| | Together AI | Pay per use | None | Open-source models | +| | Fireworks AI | Pay per use | None | Fast FLUX images | +| | Cerebras | Pay per use | None | Wafer-scale speed | +| | Cohere | Pay per use | None | Command R+ RAG | +| | NVIDIA NIM | Pay per use | None | Enterprise models | +| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free | +| | Qwen | $0 | Unlimited | 3 models free | +| | Kiro | $0 | Unlimited | Claude free | -**💡专业提示：** 从 Gemini CLI（180K 免费/月）+ iFlow（无限免费）组合开始 = 0 美元成本！ +**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- -## 🎯 使用案例 +## 🎯 Use Cases -### 案例 1：“我订阅了 Claude Pro” +### Case 1: "I have Claude Pro subscription" -**问题：** 未使用的配额过期，繁重编码期间的速率限制 +**Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" @@ -63,9 +63,9 @@ Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` -### 案例 2：“我想要零成本” +### Case 2: "I want zero cost" -**问题：** 无力订阅，需要可靠的人工智能编码 +**Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" @@ -77,9 +77,9 @@ Monthly cost: $0 Quality: Production-ready models ``` -### 案例 3：“我需要 24/7 不间断编码” +### Case 3: "I need 24/7 coding, no interruptions" -**问题：** 截止日期，无法承受停机时间 +**Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" @@ -93,9 +93,9 @@ Result: 5 layers of fallback = zero downtime Monthly cost: $20-200 (subscriptions) + $10-20 (backup) ``` -### 案例 4：“我想要 OpenClaw 中的免费 AI” +### Case 4: "I want FREE AI in OpenClaw" -**问题：** 需要在消息应用程序中使用人工智能助手，完全免费 +**Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" @@ -109,11 +109,11 @@ Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... --- -## 📖 提供商设置 +## 📖 Provider Setup -### 🔐 订阅提供商 +### 🔐 Subscription Providers -#### 克劳德代码（Pro/Max） +#### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code @@ -126,9 +126,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**专业提示：** 使用 Opus 来完成复杂的任务，使用 Sonnet 来提高速度。 OmniRoute 跟踪每个模型的配额！ +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -#### OpenAI Codex（增强版/专业版） +#### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -140,7 +140,7 @@ Models: cx/gpt-5.1-codex-max ``` -#### Gemini CLI（免费 180K/月！） +#### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -152,9 +152,9 @@ Models: gc/gemini-2.5-pro ``` -**最超值：** 巨大的免费套餐！在付费等级之前使用此功能。 +**Best Value:** Huge free tier! Use this before paid tiers. -#### GitHub 副驾驶 +#### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -167,31 +167,33 @@ Models: gh/gemini-3-pro ``` -### 💰 廉价提供商 +### 💰 Cheap Providers -#### GLM-4.7（每日重置，0.6 美元/100 万美元） +#### GLM-4.7 (Daily reset, $0.6/1M) -1. 注册：[Zhipu AI](https://open.bigmodel.cn/) -2. 从 Coding Plan 获取 API 密钥 -3. 控制面板 → 添加 API 密钥：提供商：`glm`，API 密钥：`your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` -**使用：** `glm/glm-4.7` — **专业提示：** Coding Plan 以 1/7 的成本提供 3× 配额！每天上午 10:00 重置。 +**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -#### MiniMax M2.1（5 小时重置，0.20 美元/100 万美元） +#### MiniMax M2.1 (5h reset, $0.20/1M) -1. 注册：[MiniMax](https://www.minimax.io/) 2.获取API密钥→仪表板→添加API密钥 +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key → Dashboard → Add API Key -**使用：** `minimax/MiniMax-M2.1` — **专业提示：** 长上下文（1M 令牌）的最便宜选择！ +**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)! -#### Kimi K2（每月 9 美元） +#### Kimi K2 ($9/month flat) -1.订阅：[Moonshot AI](https://platform.moonshot.ai/) 2.获取API密钥→仪表板→添加API密钥 +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key → Dashboard → Add API Key -**使用：** `kimi/kimi-latest` — **专业提示：** 固定 9 美元/月 1000 万个代币 = 0.90 美元/100 万个有效成本！ +**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! -### 🆓 免费提供商 +### 🆓 FREE Providers -#### iFlow（8 个免费模型） +#### iFlow (8 FREE models) ```bash Dashboard → Connect iFlow → OAuth login → Unlimited usage @@ -199,7 +201,7 @@ Dashboard → Connect iFlow → OAuth login → Unlimited usage Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 ``` -#### Qwen（3 个免费模型） +#### Qwen (3 FREE models) ```bash Dashboard → Connect Qwen → Device code auth → Unlimited usage @@ -207,7 +209,7 @@ Dashboard → Connect Qwen → Device code auth → Unlimited usage Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash ``` -#### Kiro（克劳德·自由） +#### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited @@ -217,9 +219,9 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 --- -## 🎨 组合 +## 🎨 Combos -### 示例 1：最大化订阅 → 廉价备份 +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -233,7 +235,7 @@ Models: Use in CLI: premium-coding ``` -### 示例 2：仅免费（零成本） +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -247,9 +249,9 @@ Cost: $0 forever! --- -## 🔧 CLI 集成 +## 🔧 CLI Integration -### 光标 IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -258,9 +260,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### 克劳德·代码 +### Claude Code -编辑 `~/.claude/config.json`： +Edit `~/.claude/config.json`: ```json { @@ -277,9 +279,9 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### 开爪 +### OpenClaw -编辑 `~/.openclaw/openclaw.json`： +Edit `~/.openclaw/openclaw.json`: ```json { @@ -301,9 +303,9 @@ codex "your prompt" } ``` -**或使用仪表板：** CLI 工具 → OpenClaw → 自动配置 +**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config -### 克莱恩 / 继续 / RooCode +### Cline / Continue / RooCode ``` Provider: OpenAI Compatible @@ -314,9 +316,28 @@ Model: cc/claude-opus-4-6 --- -## 🚀 部署 +## 🚀 Deployment -### VPS 部署 +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -335,7 +356,44 @@ npm run start # Or: pm2 start npm --name omniroute -- start ``` -### 码头工人 +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker ```bash # Build image (default = runner-cli with codex/claude/droid preinstalled) @@ -345,81 +403,84 @@ docker build -t omniroute:cli . docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` -对于使用 CLI 二进制文件的主机集成模式，请参阅主文档中的 Docker 部分。 +For host-integrated mode with CLI binaries, see the Docker section in the main docs. -### 环境变量 +### Environment Variables -| 变量 | 默认 | 描述 | -| --------------------- | ------------------------------------ | -------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 签名秘密（**生产变更**） | -| `INITIAL_PASSWORD` | `123456` | 首次登录密码 | -| `DATA_DIR` | `~/.omniroute` | 数据目录（数据库、使用情况、日志） | -| `PORT` | 框架默认 | 服务端口（示例中为 `20128`） | -| `HOSTNAME` | 框架默认 | 绑定主机（Docker 默认为 `0.0.0.0`） | -| `NODE_ENV` | 运行时默认 | 设置 `production` 进行部署 | -| `BASE_URL` | `http://localhost:20128` | 服务器端内部基本 URL | -| `CLOUD_URL` | `https://omniroute.dev` | 云同步端点基本 URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | 生成的 API 密钥的 HMAC 秘密 | -| `REQUIRE_API_KEY` | `false` | 在 `/v1/*` 上强制执行 Bearer API 密钥 | -| `ENABLE_REQUEST_LOGS` | `false` | 启用请求/响应日志 | -| `AUTH_COOKIE_SECURE` | `false` | 强制 `Secure` auth cookie（在 HTTPS 反向代理后面） | +| Variable | Default | Description | +| ------------------------- | ------------------------------------ | ------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | +| `INITIAL_PASSWORD` | `123456` | First login password | +| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | +| `PORT` | framework default | Service port (`20128` in examples) | +| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | +| `NODE_ENV` | runtime default | Set `production` for deploy | +| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | +| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | +| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | -有关完整环境变量参考，请参阅 [README](../README.md)。 +For the full environment variable reference, see the [README](../README.md). --- -## 📊 可用型号 +## 📊 Available Models
-查看所有可用型号 +View all available models -**克劳德代码 (`cc/`)** — Pro/Max：`cc/claude-opus-4-6`、`cc/claude-sonnet-4-5-20250929`、`cc/claude-haiku-4-5-20251001` +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` -**法典 (`cx/`)** — 增强版/专业版：`cx/gpt-5.2-codex`、`cx/gpt-5.1-codex-max` +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` -**Gemini CLI (`gc/`)** — 免费：`gc/gemini-3-flash-preview`、`gc/gemini-2.5-pro` +**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` -**GitHub Copilot (`gh/`)**：`gh/gpt-5`、`gh/claude-4.5-sonnet` +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` -**GLM (`glm/`)** — 0.6 美元/100 万美元：`glm/glm-4.7` +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` -**MiniMax (`minimax/`)** — 0.2 美元/100 万美元：`minimax/MiniMax-M2.1` +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` -**iFlow (`if/`)** — 免费：`if/kimi-k2-thinking`、`if/qwen3-coder-plus`、`if/deepseek-r1` +**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` -**Qwen (`qw/`)** — 免费：`qw/qwen3-coder-plus`、`qw/qwen3-coder-flash` +**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` -**Kiro (`kr/`)** — 免费：`kr/claude-sonnet-4.5`、`kr/claude-haiku-4.5` +**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` -**DeepSeek (`ds/`)**：`ds/deepseek-chat`、`ds/deepseek-reasoner` +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` -**Groq (`groq/`)**：`groq/llama-3.3-70b-versatile`、`groq/llama-4-maverick-17b-128e-instruct` +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` -**xAI (`xai/`)**：`xai/grok-4`、`xai/grok-4-0709-fast-reasoning`、`xai/grok-code-mini` +**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` -**米斯特拉尔 (`mistral/`)**：`mistral/mistral-large-2501`、`mistral/codestral-2501` +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` -**困惑 (`pplx/`)**：`pplx/sonar-pro`、`pplx/sonar` +**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` -**一起人工智能 (`together/`)**：`together/meta-llama/Llama-3.3-70B-Instruct-Turbo` +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` -**烟花人工智能 (`fireworks/`)**：`fireworks/accounts/fireworks/models/deepseek-v3p1` +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` -**Cerebras (`cerebras/`)**：`cerebras/llama-3.3-70b` +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` -**一致 (`cohere/`)**：`cohere/command-r-plus-08-2024` +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` -**NVIDIA NIM (`nvidia/`)**：`nvidia/nvidia/llama-3.3-70b-instruct` +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
--- -## 🧩 高级功能 +## 🧩 Advanced Features -### 定制模型 +### Custom Models -将任何模型 ID 添加到任何提供商，无需等待应用程序更新： +Add any model ID to any provider without waiting for an app update: ```bash # Via API @@ -431,11 +492,11 @@ curl -X POST http://localhost:20128/api/provider-models \ # Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" ``` -或者使用仪表板：**提供商 → [提供商] → 自定义模型**。 +Or use Dashboard: **Providers → [Provider] → Custom Models**. -### 专用提供商路线 +### Dedicated Provider Routes -通过模型验证将请求直接路由到特定提供者： +Route requests directly to a specific provider with model validation: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions @@ -443,9 +504,9 @@ POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` -如果缺少提供商前缀，则会自动添加。不匹配的模型返回 `400`。 +The provider prefix is auto-added if missing. Mismatched models return `400`. -### 网络代理配置 +### Network Proxy Configuration ```bash # Set global proxy @@ -461,76 +522,76 @@ curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` -**优先级：**特定于键→特定于组合→特定于提供者→全局→环境。 +**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment. -### 模型目录 API +### Model Catalog API ```bash curl http://localhost:20128/api/models/catalog ``` -返回按类型（`chat`、`embedding`、`image`）提供者分组的模型。 +Returns models grouped by provider with types (`chat`, `embedding`, `image`). -### 云同步 +### Cloud Sync -- 跨设备同步提供商、组合和设置 -- 自动后台同步，带超时+快速失败 -- 在生产中更喜欢服务器端 `BASE_URL`/`CLOUD_URL` +- Sync providers, combos, and settings across devices +- Automatic background sync with timeout + fail-fast +- Prefer server-side `BASE_URL`/`CLOUD_URL` in production -### LLM Gateway Intelligence（第 9 阶段） +### LLM Gateway Intelligence (Phase 9) -- **语义缓存** — 自动缓存非流式传输、温度=0 响应（使用 `X-OmniRoute-No-Cache: true` 绕过） -- **请求幂等性** — 通过 `Idempotency-Key` 或 `X-Request-Id` 标头在 5 秒内删除重复请求 -- **进度跟踪** — 通过 `X-OmniRoute-Progress: true` 标头选择加入 SSE `event: progress` 事件 +- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) +- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header +- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header --- -### 翻译游乐场 +### Translator Playground -通过**仪表板 → 翻译器**访问。调试并可视化 OmniRoute 如何在提供者之间转换 API 请求。 +Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers. -| 模式 | 目的 | -| -------------- | ------------------------------------------------- | -| **游乐场** | 选择源/目标格式，粘贴请求，然后立即查看翻译的输出 | -| **聊天测试仪** | 通过代理发送实时聊天消息并检查完整的请求/响应周期 | -| **测试台** | 跨多种格式组合运行批量测试以验证翻译的正确性 | -| **实时监控** | 当请求流经代理时观看实时翻译 | +| Mode | Purpose | +| ---------------- | -------------------------------------------------------------------------------------- | +| **Playground** | Select source/target formats, paste a request, and see the translated output instantly | +| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle | +| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness | +| **Live Monitor** | Watch real-time translations as requests flow through the proxy | -**使用案例：** +**Use cases:** -- 调试特定客户端/提供商组合失败的原因 -- 验证思维标签、工具调用和系统提示是否正确翻译 -- 比较 OpenAI、Claude、Gemini 和 Responses API 格式之间的格式差异 +- Debug why a specific client/provider combination fails +- Verify that thinking tags, tool calls, and system prompts translate correctly +- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats --- -### 路由策略 +### Routing Strategies -通过**仪表板→设置→路由**进行配置。 +Configure via **Dashboard → Settings → Routing**. -| 战略 | 描述 | -| ------------------------- | ------------------------------------------------------------------- | -| **先填写** | 按优先级顺序使用帐户 — 主帐户处理所有请求，直到不可用为止 | -| **循环赛** | 循环浏览所有帐户，并具有可配置的粘性限制（默认：每个帐户 3 次调用） | -| **P2C（两种选择的力量）** | 随机选择 2 个账户并选择更健康的账户 — 平衡负荷与健康意识 | -| **随机** | 使用 Fisher-Yates shuffle 为每个请求随机选择一个帐户 | -| **最少使用** | 路由到具有最早 `lastUsedAt` 时间戳的帐户，均匀分配流量 | -| **成本优化** | 路由至具有最低优先级值的帐户，针对成本最低的提供商进行优化 | +| Strategy | Description | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | +| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable | +| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) | +| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health | +| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle | +| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly | +| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers | -#### 通配符模型别名 +#### Wildcard Model Aliases -创建通配符模式来重新映射模型名称： +Create wildcard patterns to remap model names: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 Pattern: gpt-* → Target: gh/gpt-5.1-codex ``` -通配符支持 `*`（任何字符）和 `?`（单个字符）。 +Wildcards support `*` (any characters) and `?` (single character). -#### 后备链 +#### Fallback Chains -定义适用于所有请求的全局后备链： +Define global fallback chains that apply across all requests: ``` Chain: production-fallback @@ -541,46 +602,46 @@ Chain: production-fallback --- -### 弹性和断路器 +### Resilience & Circuit Breakers -通过**仪表板→设置→弹性**进行配置。 +Configure via **Dashboard → Settings → Resilience**. -OmniRoute 通过四个组件实现提供商级弹性： +OmniRoute implements provider-level resilience with four components: -1. **提供商配置文件** — 每个提供商的配置： - - 失败阈值（打开前有多少次失败） - - 冷却时间 - - 速率限制检测灵敏度 - - 指数退避参数 +1. **Provider Profiles** — Per-provider configuration for: + - Failure threshold (how many failures before opening) + - Cooldown duration + - Rate limit detection sensitivity + - Exponential backoff parameters -2. **可编辑的速率限制** — 可在仪表板中配置的系统级默认值： - - **每分钟请求数 (RPM)** — 每个帐户每分钟最大请求数 - - **请求之间的最小时间** — 请求之间的最小间隔（以毫秒为单位） - - **最大并发请求** — 每个帐户的最大并发请求数 - - 点击**编辑**进行修改，然后点击**保存**或**取消**。价值通过弹性 API 得以保留。 +2. **Editable Rate Limits** — System-level defaults configurable in the dashboard: + - **Requests Per Minute (RPM)** — Maximum requests per minute per account + - **Min Time Between Requests** — Minimum gap in milliseconds between requests + - **Max Concurrent Requests** — Maximum simultaneous requests per account + - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API. -3. **断路器** — 跟踪每个提供商的故障并在达到阈值时自动打开电路： - - **CLOSED**（健康）— 请求正常流动 - - **OPEN** — 提供商在多次失败后被暂时阻止 - - **HALF_OPEN** — 测试提供商是否已恢复 +3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached: + - **CLOSED** (Healthy) — Requests flow normally + - **OPEN** — Provider is temporarily blocked after repeated failures + - **HALF_OPEN** — Testing if provider has recovered -4. **策略和锁定标识符** — 显示断路器状态和具有强制解锁功能的锁定标识符。 +4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability. -5. **速率限制自动检测** — 监控 `429` 和 `Retry-After` 标头，以主动避免达到提供商速率限制。 +5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits. -**专业提示：** 当提供商从中断中恢复时，使用 **全部重置** 按钮可以清除所有断路器和冷却时间。 +**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage. --- -### 数据库导出/导入 +### Database Export / Import -在**仪表板→设置→系统和存储**中管理数据库备份。 +Manage database backups in **Dashboard → Settings → System & Storage**. -| 行动 | 描述 | -| ---------------------- | ---------------------------------------------------------------------------------- | -| **导出数据库** | 将当前 SQLite 数据库下载为 `.sqlite` 文件 | -| **全部导出 (.tar.gz)** | 下载完整的备份存档，包括：数据库、设置、组合、提供商连接（无凭据）、API 密钥元数据 | -| **导入数据库** | 上传 `.sqlite` 文件以替换当前数据库。自动创建导入前备份 | +| Action | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| **Export Database** | Downloads the current SQLite database as a `.sqlite` file | +| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata | +| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created | ```bash # API: Export database @@ -594,38 +655,38 @@ curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` -**导入验证：** 验证导入文件的完整性（SQLite 编译指示检查）、所需表（`provider_connections`、`provider_nodes`、`combos`、`api_keys`）和大小（最大 100MB）。 +**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB). -**使用案例：** +**Use Cases:** -- 在机器之间迁移 OmniRoute -- 创建外部备份以进行灾难恢复 -- 在团队成员之间共享配置（导出全部→共享存档） +- Migrate OmniRoute between machines +- Create external backups for disaster recovery +- Share configurations between team members (export all → share archive) --- -### 设置仪表板 +### Settings Dashboard -设置页面分为 5 个选项卡，以便于导航： +The settings page is organized into 5 tabs for easy navigation: -| 选项卡 | 内容 | -| ------------ | ----------------------------------------------------------------- | -| **安全** | 登录/密码设置、IP 访问控制、`/models` 的 API 身份验证和提供商阻止 | -| **路由** | 全局路由策略（6 个选项）、通配符模型别名、后备链、组合默认值 | -| **弹性** | 提供商资料、可编辑的速率限制、断路器状态、策略和锁定标识符 | -| **人工智能** | 思维预算配置、全局系统提示注入、提示缓存统计 | -| **高级** | 全局代理配置（HTTP/SOCKS5） | +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | --- -### 成本和预算管理 +### Costs & Budget Management -通过**仪表板 → 成本**访问。 +Access via **Dashboard → Costs**. -| 选项卡 | 目的 | -| -------- | ------------------------------------------------------------ | -| **预算** | 通过每日/每周/每月预算和实时跟踪设置每个 API 密钥的支出限额 | -| **定价** | 查看和编辑模型定价条目 - 每个提供商每 1K 输入/输出代币的成本 | +| Tab | Purpose | +| ----------- | ---------------------------------------------------------------------------------------- | +| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking | +| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider | ```bash # API: Set a budget @@ -637,13 +698,13 @@ curl -X POST http://localhost:20128/api/usage/budget \ curl http://localhost:20128/api/usage/budget ``` -**成本跟踪：** 每个请求都会记录令牌使用情况并使用定价表计算成本。按提供商、型号和 API 密钥查看 **仪表板 → 使用情况** 中的细分。 +**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key. --- -### 音频转录 +### Audio Transcription -OmniRoute 支持通过 OpenAI 兼容端点进行音频转录： +OmniRoute supports audio transcription via the OpenAI-compatible endpoint: ```bash POST /v1/audio/transcriptions @@ -657,40 +718,92 @@ curl -X POST http://localhost:20128/v1/audio/transcriptions \ -F "model=deepgram/nova-3" ``` -可用提供程序：**Deepgram** (`deepgram/`)、**AssemblyAI** (`assemblyai/`)。 +Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). -支持的音频格式：`mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。 +Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- -### 组合平衡策略 +### Combo Balancing Strategies -在**仪表板→组合→创建/编辑→策略**中配置每个组合的平衡。 +Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**. -| 战略 | 描述 | -| ------------ | ---------------------------------------- | -| **循环赛** | 按顺序轮换模型 | -| **优先** | 总是尝试第一个模型；仅在错误时才回退 | -| **随机** | 为每个请求从组合中选择一个随机模型 | -| **加权** | 根据每个模型分配的权重按比例路由 | -| **最少使用** | 路由到最近请求最少的模型（使用组合指标） | -| **成本优化** | 通往最便宜可用型号的路线（使用定价表） | +| Strategy | Description | +| ------------------ | ------------------------------------------------------------------------ | +| **Round-Robin** | Rotates through models sequentially | +| **Priority** | Always tries the first model; falls back only on error | +| **Random** | Picks a random model from the combo for each request | +| **Weighted** | Routes proportionally based on assigned weights per model | +| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) | +| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) | -全局组合默认值可以在**仪表板→设置→路由→组合默认值**中设置。 +Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**. --- -### 健康仪表板 +### Health Dashboard -通过**仪表板→健康**访问。 6张卡实时系统健康概览： +Access via **Dashboard → Health**. Real-time system health overview with 6 cards: -| 卡 | 它显示了什么 | -| -------------- | ------------------------------------------ | -| **系统状态** | 正常运行时间、版本、内存使用情况、数据目录 | -| **提供者健康** | 每个提供商的断路器状态（闭合/打开/半开） | -| **速率限制** | 每个帐户的活动速率限制冷却时间和剩余时间 | -| **主动锁定** | 供应商因封锁政策而暂时被封锁 | -| **签名缓存** | 重复数据删除缓存统计信息（活动键、命中率） | -| **延迟遥测** | 每个提供商的 p50/p95/p99 延迟聚合 | +| Card | What It Shows | +| --------------------- | ----------------------------------------------------------- | +| **System Status** | Uptime, version, memory usage, data directory | +| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) | +| **Rate Limits** | Active rate limit cooldowns per account with remaining time | +| **Active Lockouts** | Providers temporarily blocked by the lockout policy | +| **Signature Cache** | Deduplication cache stats (active keys, hit rate) | +| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider | -**专业提示：** 健康页面每 10 秒自动刷新一次。使用断路器卡来识别哪些提供商遇到问题。 +**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues. + +--- + +## 🖥️ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Installation + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output → `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) | + +📖 Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/mcp-server.md b/docs/mcp-server.md new file mode 100644 index 0000000000..5de3579f5e --- /dev/null +++ b/docs/mcp-server.md @@ -0,0 +1,83 @@ +# OmniRoute MCP Server Documentation + +> Model Context Protocol server with 16 intelligent tools + +## Installation + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/package-lock.json b/package-lock.json index c3fc223c25..0779c40e34 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "omniroute", - "version": "2.0.11", + "version": "2.0.12", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "omniroute", - "version": "2.0.11", + "version": "2.0.12", "hasInstallScript": true, "license": "MIT", "workspaces": [ diff --git a/package.json b/package.json index 28121864fd..179d78d390 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "omniroute", - "version": "2.0.12", + "version": "2.0.13", "description": "Smart AI Router with auto fallback — route to FREE & cheap models, zero downtime. Works with Cursor, Cline, Claude Desktop, Codex, and any OpenAI-compatible tool.", "type": "module", "bin": {