mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-07 15:52:52 +03:00
docs: update root files to v3.4.2 state, cleanup obsolete files
- SECURITY.md: supported versions 3.4.x/3.0.x, MCP scopes (10), audit trail, Zod v4 validation, TLS/CLI fingerprint - CONTRIBUTING.md: Node >=18<24, port 20128, project structure (21 DB modules, 25 MCP tools, memory/skills/electron), 122 test files - README.md: 60+ providers, 25 MCP tools, 10 scopes, 9 strategies - .dockerignore: expanded exclusions (tests, docs, electron, *.tgz) - .npmignore: added llm.txt, bun.lock, tsconfig variants, subprojects - .gitignore: _*/ dirs, docs/new-features, COVERAGE_PLAN allowlist Deleted files: - 20 README.*.md redirect stubs (consolidated in docs/i18n/) - 4 scratch test files (test_exception/target_format/translator/out) - restart.sh, validate-translation.sh (obsolete scripts) - Moved COVERAGE_PLAN.md -> docs/COVERAGE_PLAN.md
This commit is contained in:
diegosouzapw
@@ -30,3 +30,40 @@ npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
.pnpm-debug.log*
|
||||
|
||||
# Test suites
|
||||
tests
|
||||
test-results
|
||||
playwright-report
|
||||
blob-report
|
||||
|
||||
# Documentation (not needed in container)
|
||||
docs
|
||||
*.md
|
||||
!README.md
|
||||
|
||||
# Electron (separate build)
|
||||
electron
|
||||
|
||||
# VS Code extension (separate project)
|
||||
vscode-extension
|
||||
|
||||
# Build artifacts
|
||||
*.tgz
|
||||
*.AppImage
|
||||
*.deb
|
||||
*.rpm
|
||||
|
||||
# Package manager lock (bun)
|
||||
bun.lock
|
||||
|
||||
# Agent config
|
||||
.agents
|
||||
.gemini
|
||||
|
||||
# Misc
|
||||
llm.txt
|
||||
images
|
||||
clipr
|
||||
omnirouteCloud
|
||||
omnirouteSite
|
||||
|
||||
15
.gitignore
vendored
15
.gitignore
vendored
@@ -5,6 +5,12 @@
|
||||
omnirouteCloud/
|
||||
omnirouteSite/
|
||||
|
||||
# Root-level underscore-prefixed directories (private/draft — never commit)
|
||||
/_*/
|
||||
|
||||
# Draft features documentation (internal only)
|
||||
docs/new-features/
|
||||
|
||||
# dependencies
|
||||
node_modules/
|
||||
/.pnp
|
||||
@@ -88,6 +94,7 @@ docs/*
|
||||
!docs/AUTO-COMBO.md
|
||||
!docs/MCP-SERVER.md
|
||||
!docs/CLI-TOOLS.md
|
||||
!docs/COVERAGE_PLAN.md
|
||||
|
||||
|
||||
# open-sse tests
|
||||
@@ -140,4 +147,10 @@ vscode-extension/
|
||||
.idea/
|
||||
|
||||
# Local OpenCode agent config
|
||||
.config/
|
||||
.config/
|
||||
|
||||
# Empty/dangling files
|
||||
typescript
|
||||
|
||||
# Gemini Antigravity agent data
|
||||
.gemini/
|
||||
13
.npmignore
13
.npmignore
@@ -26,14 +26,19 @@ scripts/
|
||||
.github/
|
||||
.husky/
|
||||
.vscode/
|
||||
.agents/
|
||||
.env*
|
||||
eslint.config.mjs
|
||||
prettier.config.mjs
|
||||
postcss.config.mjs
|
||||
next.config.mjs
|
||||
tsconfig.json
|
||||
tsconfig.typecheck-core.json
|
||||
tsconfig.typecheck-noimplicit-core.json
|
||||
playwright.config.ts
|
||||
vitest.config.ts
|
||||
next-env.d.ts
|
||||
llm.txt
|
||||
|
||||
# Docker
|
||||
docker-compose*.yml
|
||||
@@ -41,8 +46,8 @@ Dockerfile
|
||||
.dockerignore
|
||||
|
||||
# Misc
|
||||
restart.sh
|
||||
AGENTS.md
|
||||
bun.lock
|
||||
|
||||
# Build artifacts (pre-built goes inside app/)
|
||||
.next/
|
||||
@@ -56,3 +61,9 @@ node_modules/
|
||||
electron/
|
||||
app/electron/
|
||||
app/vscode-extension/
|
||||
|
||||
# Subprojects
|
||||
clipr/
|
||||
omnirouteCloud/
|
||||
omnirouteSite/
|
||||
vscode-extension/
|
||||
|
||||
135
AGENTS.md
135
AGENTS.md
@@ -3,17 +3,20 @@
|
||||
## Project
|
||||
|
||||
Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
|
||||
(OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, etc.)
|
||||
with **MCP Server** (16 tools) and **A2A v0.3 Protocol**.
|
||||
with **60+ providers** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
|
||||
Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, and many more)
|
||||
with **MCP Server** (25 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
|
||||
|
||||
## Stack
|
||||
|
||||
- **Runtime**: Next.js 16 (App Router), Node.js, ES Modules (`"type": "module"`)
|
||||
- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`)
|
||||
- **Runtime**: Next.js 16 (App Router), Node.js ≥18 <24, ES Modules (`"type": "module"`)
|
||||
- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`, `electron/`)
|
||||
- **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/`
|
||||
- **Streaming**: SSE via `open-sse` internal package
|
||||
- **Streaming**: SSE via `open-sse` internal workspace package
|
||||
- **Styling**: Tailwind CSS v4
|
||||
- **i18n**: next-intl with 30 languages
|
||||
- **Desktop**: Electron (cross-platform: Windows, macOS, Linux)
|
||||
- **Schemas**: Zod v4 for all API / MCP input validation
|
||||
|
||||
---
|
||||
|
||||
@@ -30,11 +33,13 @@ with **MCP Server** (16 tools) and **A2A v0.3 Protocol**.
|
||||
| `npm run typecheck:noimplicit:core` | Strict checking (no implicit any) |
|
||||
| `npm run check` | Run lint + test |
|
||||
| `npm run check:cycles` | Check for circular dependencies |
|
||||
| `npm run electron:dev` | Run Electron app in dev mode |
|
||||
| `npm run electron:build` | Build Electron app for current OS |
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# All tests
|
||||
# All tests (unit + vitest + ecosystem + e2e)
|
||||
npm run test:all
|
||||
|
||||
# Single test file (Node.js native test runner — most tests use this)
|
||||
@@ -52,7 +57,13 @@ npm run test:vitest
|
||||
# E2E with Playwright
|
||||
npm run test:e2e
|
||||
|
||||
# Coverage (55% min thresholds)
|
||||
# Protocol clients E2E (MCP transports, A2A)
|
||||
npm run test:protocols:e2e
|
||||
|
||||
# Ecosystem compatibility tests
|
||||
npm run test:ecosystem
|
||||
|
||||
# Coverage (55% min thresholds — statements, lines, functions; 60% branches)
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
@@ -69,19 +80,19 @@ Always run `prettier --write` on changed files.
|
||||
|
||||
- **Target**: ES2022 · **Module**: `esnext` · **Resolution**: `bundler`
|
||||
- `strict: false` — prefer explicit types, don't rely on inference
|
||||
- Path aliases: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`
|
||||
- Path aliases: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
|
||||
|
||||
### ESLint Rules
|
||||
|
||||
- **Security (error, everywhere)**: `no-eval`, `no-implied-eval`, `no-new-func`
|
||||
- **Relaxed in `open-sse/` and `tests/`**: `@typescript-eslint/no-explicit-any` = warn
|
||||
- React hooks rules disabled in `open-sse/`
|
||||
- React hooks rules and `@next/next/no-assign-module-variable` disabled in `open-sse/` and `tests/`
|
||||
|
||||
### Naming
|
||||
|
||||
| Element | Convention | Example |
|
||||
| ------------------- | -------------------------------- | ------------------------------------ |
|
||||
| Files | kebab-case | `chatCore.ts`, `tokenHealthCheck.ts` |
|
||||
| Files | camelCase / kebab-case | `chatCore.ts`, `tokenHealthCheck.ts` |
|
||||
| React components | PascalCase | `Dashboard.tsx`, `ProviderCard.tsx` |
|
||||
| Functions/variables | camelCase | `getHealth()`, `switchCombo()` |
|
||||
| Constants | UPPER_SNAKE | `MAX_RETRIES`, `DEFAULT_TIMEOUT` |
|
||||
@@ -113,33 +124,124 @@ Always run `prettier --write` on changed files.
|
||||
|
||||
### Data Layer (`src/lib/db/`)
|
||||
|
||||
All persistence uses SQLite through domain-specific modules (`core.ts`, `providers.ts`,
|
||||
`models.ts`, `combos.ts`, `apiKeys.ts`, `settings.ts`, `backup.ts`).
|
||||
All persistence uses SQLite through domain-specific modules:
|
||||
`core.ts`, `providers.ts`, `models.ts`, `combos.ts`, `apiKeys.ts`, `settings.ts`,
|
||||
`backup.ts`, `proxies.ts`, `prompts.ts`, `webhooks.ts`, `detailedLogs.ts`,
|
||||
`domainState.ts`, `registeredKeys.ts`, `quotaSnapshots.ts`, `modelComboMappings.ts`,
|
||||
`cliToolState.ts`, `encryption.ts`, `readCache.ts`, `secrets.ts`, `stateReset.ts`.
|
||||
Schema migrations live in `db/migrations/` and run via `migrationRunner.ts`.
|
||||
`src/lib/localDb.ts` is a **re-export layer only** — never add logic there.
|
||||
|
||||
### Request Pipeline (`open-sse/`)
|
||||
|
||||
`chatCore.ts` → executor → upstream provider. Translations in `open-sse/translator/`.
|
||||
|
||||
**Handlers** (`open-sse/handlers/`): `chatCore.ts`, `responsesHandler.ts`, `embeddings.ts`,
|
||||
`imageGeneration.ts`, `videoGeneration.ts`, `musicGeneration.ts`, `audioSpeech.ts`,
|
||||
`audioTranscription.ts`, `moderations.ts`, `rerank.ts`, `search.ts`.
|
||||
|
||||
**Upstream headers**: merged after default auth; same header name replaces executor value.
|
||||
**T5 intra-family fallback** recomputes headers using only the fallback model id.
|
||||
Forbidden header names: `src/shared/constants/upstreamHeaders.ts` — keep sanitize,
|
||||
Zod schemas, and unit tests aligned when editing.
|
||||
|
||||
### Provider Categories
|
||||
|
||||
- **Free** (4): Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
|
||||
- **OAuth** (8): Claude Code, Antigravity, Codex, GitHub Copilot, Cursor, Kimi Coding, Kilo Code, Cline
|
||||
- **API Key** (48+): OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Perplexity,
|
||||
Together, Fireworks, Cerebras, Cohere, NVIDIA, Nebius, SiliconFlow, Hyperbolic,
|
||||
HuggingFace, OpenRouter, Vertex AI, Cloudflare AI, Scaleway, AI/ML API, Pollinations,
|
||||
Puter, Longcat, Alibaba, Kimi, Minimax, Blackbox, Synthetic, Kilo Gateway,
|
||||
Z.AI, GLM, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld,
|
||||
NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper, Brave, Exa,
|
||||
Tavily, OpenCode Zen/Go, Bailian Coding Plan, and more.
|
||||
- **Custom**: OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) prefixes
|
||||
|
||||
Providers are registered in `src/shared/constants/providers.ts` with Zod validation at module load.
|
||||
|
||||
### Executors (`open-sse/executors/`)
|
||||
|
||||
Provider-specific request executors: `base.ts`, `default.ts`, `cursor.ts`, `codex.ts`,
|
||||
`antigravity.ts`, `github.ts`, `gemini-cli.ts`, `kiro.ts`, `qoder.ts`, `vertex.ts`,
|
||||
`cloudflare-ai.ts`, `opencode.ts`, `pollinations.ts`, `puter.ts`.
|
||||
|
||||
### Translator (`open-sse/translator/`)
|
||||
|
||||
Translates between API formats (OpenAI-format ↔ Anthropic, Gemini, etc.).
|
||||
Includes request/response translators with helpers for image handling.
|
||||
|
||||
### Transformer (`open-sse/transformer/`)
|
||||
|
||||
`responsesTransformer.ts` — transforms Responses API format to/from Chat Completions format.
|
||||
|
||||
### Services (`open-sse/services/`)
|
||||
|
||||
36+ service modules including: `combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`,
|
||||
`rateLimitManager.ts`, `accountFallback.ts`, `sessionManager.ts`, `wildcardRouter.ts`,
|
||||
`autoCombo/`, `intentClassifier.ts`, `taskAwareRouter.ts`, `thinkingBudget.ts`,
|
||||
`contextManager.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`,
|
||||
`emergencyFallback.ts`, `workflowFSM.ts`, `backgroundTaskDetector.ts`, `ipFilter.ts`,
|
||||
`signatureCache.ts`, `volumeDetector.ts`, and more.
|
||||
|
||||
### Domain Layer (`src/domain/`)
|
||||
|
||||
Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`,
|
||||
`degradation.ts`, `fallbackPolicy.ts`, `lockoutPolicy.ts`, `modelAvailability.ts`,
|
||||
`providerExpiration.ts`, `quotaCache.ts`, `responses.ts`, `configAudit.ts`.
|
||||
|
||||
### MCP Server (`open-sse/mcp-server/`)
|
||||
|
||||
16 tools, 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (9 scopes), Zod schemas.
|
||||
25 tools, 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (10 scopes), Zod schemas.
|
||||
|
||||
**Core tools** (18): get_health, list_combos, get_combo_metrics, switch_combo, check_quota,
|
||||
route_request, cost_report, list_models_catalog, simulate_route, set_budget_guard,
|
||||
set_routing_strategy, set_resilience_profile, test_combo, get_provider_metrics,
|
||||
best_combo_for_task, explain_route, get_session_snapshot, sync_pricing.
|
||||
|
||||
**Memory tools** (3): memory_search, memory_add, memory_clear.
|
||||
|
||||
**Skill tools** (4): skills_list, skills_enable, skills_execute, skills_executions.
|
||||
|
||||
### A2A Server (`src/lib/a2a/`)
|
||||
|
||||
JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup. Agent Card at `/.well-known/agent.json`.
|
||||
JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup(
|
||||
Agent Card at `/.well-known/agent.json`.
|
||||
Skills: `quotaManagement.ts`, `smartRouting.ts`.
|
||||
|
||||
### ACP Module (`src/lib/acp/`)
|
||||
|
||||
Agent Communication Protocol registry and manager.
|
||||
|
||||
### Memory System (`src/lib/memory/`)
|
||||
|
||||
Extraction, injection, retrieval, summarization, and store modules for persistent
|
||||
conversational memory across sessions.
|
||||
|
||||
### Skills System (`src/lib/skills/`)
|
||||
|
||||
Extensible skill framework: registry, executor, sandbox, built-in skills,
|
||||
custom skill support, interception, and injection.
|
||||
|
||||
### Compliance (`src/lib/compliance/`)
|
||||
|
||||
Policy index for compliance enforcement.
|
||||
|
||||
### MITM Proxy (`src/mitm/`)
|
||||
|
||||
MITM proxy capability with certificate management, DNS handling, and target routing.
|
||||
|
||||
### Middleware (`src/middleware/`)
|
||||
|
||||
Request middleware including `promptInjectionGuard.ts`.
|
||||
|
||||
### Adding a New Provider
|
||||
|
||||
1. Register in `src/shared/constants/providers.ts`
|
||||
2. Add executor in `open-sse/executors/`
|
||||
2. Add executor in `open-sse/executors/` (if custom logic needed)
|
||||
3. Add translator in `open-sse/translator/` (if non-OpenAI format)
|
||||
4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` (if OAuth-based)
|
||||
5. Add models in `open-sse/config/providerRegistry.ts`
|
||||
|
||||
---
|
||||
|
||||
@@ -151,3 +253,6 @@ JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup. Agent Card at `/.wel
|
||||
- **No memory leaks** in SSE streams (abort signals, cleanup)
|
||||
- **Rate limit headers** must be parsed correctly
|
||||
- All API inputs validated with **Zod schemas**
|
||||
- **Provider constants** validated at module load via Zod (`src/shared/validation/providerSchema.ts`)
|
||||
- **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts`
|
||||
- **Memory/Skills** are cross-cutting: affect MCP tools, request pipeline, and A2A skills
|
||||
|
||||
184
CONTRIBUTING.md
184
CONTRIBUTING.md
@@ -8,7 +8,7 @@ Thank you for your interest in contributing! This guide covers everything you ne
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Node.js** 20+ (recommended: 22 LTS)
|
||||
- **Node.js** >= 18 < 24 (recommended: 22 LTS)
|
||||
- **npm** 10+
|
||||
- **Git**
|
||||
|
||||
@@ -33,13 +33,13 @@ echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env
|
||||
|
||||
Key variables for development:
|
||||
|
||||
| Variable | Development Default | Description |
|
||||
| ---------------------- | ----------------------- | ------------------------- |
|
||||
| `PORT` | `3000` | Server port |
|
||||
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | Base URL for frontend |
|
||||
| `JWT_SECRET` | (generate above) | JWT signing secret |
|
||||
| `INITIAL_PASSWORD` | `123456` | First login password |
|
||||
| `ENABLE_REQUEST_LOGS` | `false` | Enable debug request logs |
|
||||
| Variable | Development Default | Description |
|
||||
| ---------------------- | ------------------------ | --------------------- |
|
||||
| `PORT` | `20128` | Server port |
|
||||
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend |
|
||||
| `JWT_SECRET` | (generate above) | JWT signing secret |
|
||||
| `INITIAL_PASSWORD` | `CHANGEME` | First login password |
|
||||
| `APP_LOG_LEVEL` | `info` | Log verbosity level |
|
||||
|
||||
### Dashboard Settings
|
||||
|
||||
@@ -68,8 +68,8 @@ PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
|
||||
|
||||
Default URLs:
|
||||
|
||||
- **Dashboard**: `http://localhost:3000/dashboard`
|
||||
- **API**: `http://localhost:3000/v1`
|
||||
- **Dashboard**: `http://localhost:20128/dashboard`
|
||||
- **API**: `http://localhost:20128/v1`
|
||||
|
||||
---
|
||||
|
||||
@@ -108,28 +108,35 @@ test: add observability unit tests
|
||||
refactor(db): consolidate rate limit tables
|
||||
```
|
||||
|
||||
Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`.
|
||||
Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`.
|
||||
|
||||
---
|
||||
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
# All unit tests
|
||||
npm test
|
||||
npm run test:unit
|
||||
# All tests (unit + vitest + ecosystem + e2e)
|
||||
npm run test:all
|
||||
|
||||
# Specific test suites
|
||||
npm run test:security # Security tests
|
||||
npm run test:fixes # Fix verification tests
|
||||
# Single test file (Node.js native test runner — most tests use this)
|
||||
node --import tsx/esm --test tests/unit/your-file.test.mjs
|
||||
|
||||
# With coverage
|
||||
npm run test:coverage
|
||||
npm run coverage:report
|
||||
# Vitest (MCP server, autoCombo, cache)
|
||||
npm run test:vitest
|
||||
|
||||
# E2E tests (requires Playwright)
|
||||
npm run test:e2e
|
||||
|
||||
# Protocol clients E2E (MCP transports, A2A)
|
||||
npm run test:protocols:e2e
|
||||
|
||||
# Ecosystem compatibility tests
|
||||
npm run test:ecosystem
|
||||
|
||||
# Coverage (55% min statements/lines/functions; 60% branches)
|
||||
npm run test:coverage
|
||||
npm run coverage:report
|
||||
|
||||
# Lint + format check
|
||||
npm run lint
|
||||
npm run check
|
||||
@@ -140,25 +147,29 @@ Coverage notes:
|
||||
- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**`
|
||||
- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run
|
||||
- `npm run test:coverage:legacy` preserves the older metric for historical comparison
|
||||
- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap
|
||||
|
||||
Current test status: **968+ unit tests** covering:
|
||||
Current test status: **122 unit test files** covering:
|
||||
|
||||
- Provider translators and format conversion
|
||||
- Rate limiting, circuit breaker, and resilience
|
||||
- Semantic cache, idempotency, progress tracking
|
||||
- Database operations and schema
|
||||
- Database operations and schema (21 DB modules)
|
||||
- OAuth flows and authentication
|
||||
- API endpoint validation
|
||||
- API endpoint validation (Zod v4)
|
||||
- MCP server tools and scope enforcement
|
||||
- Memory and Skills systems
|
||||
|
||||
---
|
||||
|
||||
## Code Style
|
||||
|
||||
- **ESLint** — Run `npm run lint` before committing
|
||||
- **Prettier** — Auto-formatted via `lint-staged` on commit
|
||||
- **TypeScript** — All `src/` code uses `.ts`/`.tsx`; document with TSDoc (`@param`, `@returns`, `@throws`)
|
||||
- **Prettier** — Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas)
|
||||
- **TypeScript** — All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`)
|
||||
- **No `eval()`** — ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func`
|
||||
- **Zod validation** — Use Zod schemas for API input validation
|
||||
- **Zod validation** — Use Zod v4 schemas for all API input validation
|
||||
- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE
|
||||
|
||||
---
|
||||
|
||||
@@ -166,40 +177,60 @@ Current test status: **968+ unit tests** covering:
|
||||
|
||||
```
|
||||
src/ # TypeScript (.ts / .tsx)
|
||||
├── app/ # Next.js App Router
|
||||
│ ├── (dashboard)/ # Dashboard pages (.tsx)
|
||||
│ ├── api/ # API routes (.ts)
|
||||
├── app/ # Next.js 16 App Router
|
||||
│ ├── (dashboard)/ # Dashboard pages (23 sections)
|
||||
│ ├── api/ # API routes (51 directories)
|
||||
│ └── login/ # Auth pages (.tsx)
|
||||
├── domain/ # Domain types and response helpers (.ts)
|
||||
├── domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.)
|
||||
├── lib/ # Core business logic (.ts)
|
||||
│ ├── db/ # SQLite database layer
|
||||
│ ├── oauth/ # OAuth services per provider
|
||||
│ ├── cacheLayer.ts # LRU cache
|
||||
│ ├── semanticCache.ts # Semantic response cache
|
||||
│ ├── idempotencyLayer.ts # Request deduplication
|
||||
│ └── localDb.ts # Settings facade (LowDB for config, SQLite for domain data)
|
||||
│ ├── a2a/ # Agent-to-Agent v0.3 protocol server
|
||||
│ ├── acp/ # Agent Communication Protocol registry
|
||||
│ ├── compliance/ # Compliance policy engine
|
||||
│ ├── db/ # SQLite database layer (21 modules + 16 migrations)
|
||||
│ ├── memory/ # Persistent conversational memory
|
||||
│ ├── oauth/ # OAuth providers, services, and utilities
|
||||
│ ├── skills/ # Extensible skill framework
|
||||
│ ├── usage/ # Usage tracking and cost calculation
|
||||
│ └── localDb.ts # Re-export layer only — never add logic here
|
||||
├── middleware/ # Request middleware (promptInjectionGuard)
|
||||
├── mitm/ # MITM proxy (cert, DNS, target routing)
|
||||
├── shared/
|
||||
│ ├── components/ # React components (.tsx)
|
||||
│ ├── middleware/ # Correlation IDs, etc.
|
||||
│ ├── utils/ # Circuit breaker, sanitizer, etc.
|
||||
│ └── validation/ # Zod schemas
|
||||
└── sse/ # SSE chat handlers (.ts)
|
||||
│ ├── constants/ # Provider definitions (60+), MCP scopes, routing strategies
|
||||
│ ├── utils/ # Circuit breaker, sanitizer, auth helpers
|
||||
│ └── validation/ # Zod v4 schemas
|
||||
└── sse/ # SSE proxy pipeline
|
||||
|
||||
open-sse/ # @omniroute/open-sse workspace (JavaScript)
|
||||
├── handlers/ # chatCore.js — main request handler
|
||||
├── services/ # Rate limit, fallback
|
||||
├── translators/ # Format converters (OpenAI ↔ Claude ↔ Gemini)
|
||||
└── utils/ # Progress tracker, stream helpers
|
||||
open-sse/ # @omniroute/open-sse workspace
|
||||
├── executors/ # 14 provider-specific request executors
|
||||
├── handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.)
|
||||
├── mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes)
|
||||
├── services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.)
|
||||
├── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
|
||||
├── transformer/ # Responses API transformer
|
||||
└── utils/ # 22 utility modules (stream, TLS, proxy, logging)
|
||||
|
||||
electron/ # Electron desktop app (cross-platform)
|
||||
|
||||
tests/
|
||||
├── unit/ # Node.js test runner (.test.mjs)
|
||||
└── e2e/ # Playwright tests
|
||||
├── unit/ # Node.js test runner (122 test files)
|
||||
├── integration/ # Integration tests
|
||||
├── e2e/ # Playwright tests
|
||||
├── security/ # Security tests
|
||||
├── translator/ # Translator-specific tests
|
||||
└── load/ # Load tests
|
||||
|
||||
docs/ # Documentation
|
||||
├── USER_GUIDE.md # Provider setup, CLI integration
|
||||
├── API_REFERENCE.md # All endpoints
|
||||
├── TROUBLESHOOTING.md # Common issues
|
||||
├── ARCHITECTURE.md # System architecture
|
||||
├── API_REFERENCE.md # All endpoints
|
||||
├── USER_GUIDE.md # Provider setup, CLI integration
|
||||
├── TROUBLESHOOTING.md # Common issues
|
||||
├── MCP-SERVER.md # MCP server (25 tools)
|
||||
├── A2A-SERVER.md # A2A agent protocol
|
||||
├── AUTO-COMBO.md # Auto-combo engine
|
||||
├── CLI-TOOLS.md # CLI tools integration
|
||||
├── COVERAGE_PLAN.md # Test coverage improvement plan
|
||||
├── openapi.yaml # OpenAPI specification
|
||||
└── adr/ # Architecture Decision Records
|
||||
```
|
||||
|
||||
@@ -207,50 +238,25 @@ docs/ # Documentation
|
||||
|
||||
## Adding a New Provider
|
||||
|
||||
### Step 1: OAuth Service (if using OAuth)
|
||||
### Step 1: Register Provider Constants
|
||||
|
||||
Create `src/lib/oauth/services/your-provider.ts` extending `OAuthService`:
|
||||
Add to `src/shared/constants/providers.ts` — Zod-validated at module load.
|
||||
|
||||
```typescript
|
||||
import { OAuthService } from "../OAuthService";
|
||||
### Step 2: Add Executor (if custom logic needed)
|
||||
|
||||
export class YourProviderService extends OAuthService {
|
||||
constructor() {
|
||||
super({
|
||||
name: "your-provider",
|
||||
authUrl: "https://provider.com/oauth/authorize",
|
||||
tokenUrl: "https://provider.com/oauth/token",
|
||||
clientId: "...",
|
||||
scopes: ["..."],
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
Create executor in `open-sse/executors/your-provider.ts` extending the base executor.
|
||||
|
||||
### Step 2: Register Provider
|
||||
### Step 3: Add Translator (if non-OpenAI format)
|
||||
|
||||
Add to `src/lib/oauth/providers.ts`:
|
||||
Create request/response translators in `open-sse/translator/`.
|
||||
|
||||
```typescript
|
||||
import { YourProviderService } from "./services/your-provider";
|
||||
// Add to the providers map
|
||||
```
|
||||
### Step 4: Add OAuth Config (if OAuth-based)
|
||||
|
||||
### Step 3: Add Constants
|
||||
Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`.
|
||||
|
||||
Add provider constants in `src/lib/providerConstants.ts`:
|
||||
### Step 5: Register Models
|
||||
|
||||
- Provider prefix (e.g., `yp/`)
|
||||
- Default models
|
||||
- Pricing info
|
||||
|
||||
### Step 4: Add Translator (if non-OpenAI format)
|
||||
|
||||
Create translator in `open-sse/translators/` if the provider uses a custom API format.
|
||||
|
||||
### Step 5: Add Timeout
|
||||
|
||||
Add request timeout configuration in `src/shared/utils/requestTimeout.ts`.
|
||||
Add model definitions in `open-sse/config/providerRegistry.ts`.
|
||||
|
||||
### Step 6: Add Tests
|
||||
|
||||
@@ -269,6 +275,7 @@ Write unit tests in `tests/unit/` covering at minimum:
|
||||
- [ ] Build succeeds (`npm run build`)
|
||||
- [ ] TypeScript types added for new public functions and interfaces
|
||||
- [ ] No hardcoded secrets or fallback values
|
||||
- [ ] All inputs validated with Zod schemas
|
||||
- [ ] CHANGELOG updated (if user-facing change)
|
||||
- [ ] Documentation updated (if applicable)
|
||||
|
||||
@@ -276,16 +283,13 @@ Write unit tests in `tests/unit/` covering at minimum:
|
||||
|
||||
## Releasing
|
||||
|
||||
When a new GitHub Release is created (e.g. `v0.4.0`), the package is **automatically published to npm** via GitHub Actions:
|
||||
|
||||
```bash
|
||||
gh release create v0.4.0 --title "v0.4.0" --generate-notes
|
||||
```
|
||||
Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions.
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
|
||||
- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md)
|
||||
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **ADRs**: See `docs/adr/` for architectural decision records
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (ar)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/ar/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (bg)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/bg/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (cs)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/cs/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (da)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/da/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (fi)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/fi/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (he)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/he/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (hu)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/hu/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (id)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/id/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (in)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/in/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (ja)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/ja/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (ko)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/ko/README.md)**
|
||||
42
README.md
42
README.md
@@ -2,7 +2,7 @@
|
||||
|
||||
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
|
||||
|
||||
_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
|
||||
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
|
||||
|
||||
**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
|
||||
|
||||
@@ -52,7 +52,7 @@ _Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now wi
|
||||
|
||||
---
|
||||
|
||||
## 🆕 What's New in v3.0.0
|
||||
## 🆕 What's New
|
||||
|
||||
> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
|
||||
|
||||
@@ -272,7 +272,7 @@ Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve
|
||||
- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention
|
||||
- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly)
|
||||
- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next
|
||||
- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized)
|
||||
- **Custom Combos** — Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)
|
||||
- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
|
||||
|
||||
</details>
|
||||
@@ -284,7 +284,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If
|
||||
|
||||
**How OmniRoute solves it:**
|
||||
|
||||
- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ providers
|
||||
- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers
|
||||
- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
|
||||
- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+
|
||||
- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE
|
||||
@@ -370,7 +370,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code..
|
||||
- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline
|
||||
- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection
|
||||
- **Onboarding Wizard** — Guided 4-step setup for first-time users
|
||||
- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 67+ providers
|
||||
- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers
|
||||
|
||||
</details>
|
||||
|
||||
@@ -512,7 +512,7 @@ Developers who want all responses in a specific language, with a specific tone,
|
||||
|
||||
- **System Prompt Injection** — Global prompt applied to all requests
|
||||
- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive)
|
||||
- **6 Routing Strategies** — Global strategies that determine how requests are distributed
|
||||
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
|
||||
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
|
||||
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
|
||||
- **Provider Toggle** — Enable/disable all connections for a provider with one click
|
||||
@@ -579,7 +579,7 @@ Different clients should have least-privilege access to tool categories.
|
||||
|
||||
**How OmniRoute solves it:**
|
||||
|
||||
- 9 granular MCP scopes for controlled tool access
|
||||
- 10 granular MCP scopes for controlled tool access
|
||||
- Scope enforcement and visibility in MCP management UI
|
||||
- Safe default posture for operational tooling
|
||||
|
||||
@@ -1323,19 +1323,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
|
||||
|
||||
### 🤖 Agent & Protocol Operations (v2.0)
|
||||
|
||||
| Feature | What It Does |
|
||||
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| 🔧 **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
|
||||
| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |
|
||||
| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |
|
||||
| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |
|
||||
| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |
|
||||
| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |
|
||||
| 🔐 **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access |
|
||||
| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |
|
||||
| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |
|
||||
| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |
|
||||
| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |
|
||||
| Feature | What It Does |
|
||||
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 🔧 **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |
|
||||
| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |
|
||||
| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |
|
||||
| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |
|
||||
| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |
|
||||
| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |
|
||||
| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |
|
||||
| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |
|
||||
| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |
|
||||
| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |
|
||||
| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |
|
||||
|
||||
### 🧠 Routing & Intelligence
|
||||
|
||||
@@ -1346,7 +1346,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
|
||||
| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions |
|
||||
| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection |
|
||||
| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry |
|
||||
| 🎨 **Custom Combos** | 6 balancing strategies + fallback chain control |
|
||||
| 🎨 **Custom Combos** | 9 balancing strategies + fallback chain control |
|
||||
| 🌐 **Wildcard Router** | `provider/*` dynamic routing |
|
||||
| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |
|
||||
| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety |
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (ms)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/ms/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (nl)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/nl/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (no)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/no/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (phi)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/phi/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (pl)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/pl/README.md)**
|
||||
2077
README.pt.md
2077
README.pt.md
File diff suppressed because it is too large
Load Diff
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (ro)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/ro/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (sk)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/sk/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (sv)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/sv/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (th)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/th/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (uk-UA)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/uk-UA/README.md)**
|
||||
@@ -1,5 +0,0 @@
|
||||
# 🌐 OmniRoute (vi)
|
||||
|
||||
The documentation has been formalized and moved to our centralized i18n structure.
|
||||
|
||||
👉 **[Read the Documentation here](docs/i18n/vi/README.md)**
|
||||
24
SECURITY.md
24
SECURITY.md
@@ -20,9 +20,9 @@ If you discover a security vulnerability in OmniRoute, please report it responsi
|
||||
|
||||
| Version | Support Status |
|
||||
| ------- | -------------- |
|
||||
| 1.0.x | ✅ Active |
|
||||
| 0.8.x | ✅ Security |
|
||||
| < 0.8.0 | ❌ Unsupported |
|
||||
| 3.4.x | ✅ Active |
|
||||
| 3.0.x | ✅ Security |
|
||||
| < 3.0.0 | ❌ Unsupported |
|
||||
|
||||
---
|
||||
|
||||
@@ -43,6 +43,7 @@ Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer
|
||||
| **OAuth 2.0 + PKCE** | Secure provider auth (Claude, Codex, Gemini, Cursor, etc.) |
|
||||
| **Token Refresh** | Automatic OAuth token refresh before expiry |
|
||||
| **Secure Cookies** | `AUTH_COOKIE_SECURE=true` for HTTPS environments |
|
||||
| **MCP Scopes** | 10 granular scopes for MCP tool access control |
|
||||
|
||||
### 🛡️ Encryption at Rest
|
||||
|
||||
@@ -98,9 +99,11 @@ PII_REDACTION_ENABLED=true
|
||||
| Feature | Description |
|
||||
| ------------------------ | ---------------------------------------------------------------- |
|
||||
| **CORS** | Configurable origin control (`CORS_ORIGIN` env var, default `*`) |
|
||||
| **IP Filtering** | Whitelist/blacklist IP ranges in dashboard |
|
||||
| **IP Filtering** | Allowlist/blocklist IP ranges in dashboard |
|
||||
| **Rate Limiting** | Per-provider rate limits with automatic backoff |
|
||||
| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s |
|
||||
| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection |
|
||||
| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures |
|
||||
|
||||
### 🔌 Resilience & Availability
|
||||
|
||||
@@ -113,11 +116,13 @@ PII_REDACTION_ENABLED=true
|
||||
|
||||
### 📋 Compliance
|
||||
|
||||
| Feature | Description |
|
||||
| ------------------ | --------------------------------------------------- |
|
||||
| **Log Retention** | Automatic cleanup after `LOG_RETENTION_DAYS` |
|
||||
| **No-Log Opt-out** | Per API key `noLog` flag disables request logging |
|
||||
| **Audit Log** | Administrative actions tracked in `audit_log` table |
|
||||
| Feature | Description |
|
||||
| ------------------ | ----------------------------------------------------------- |
|
||||
| **Log Retention** | Automatic cleanup after `CALL_LOG_RETENTION_DAYS` |
|
||||
| **No-Log Opt-out** | Per API key `noLog` flag disables request logging |
|
||||
| **Audit Log** | Administrative actions tracked in `audit_log` table |
|
||||
| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls |
|
||||
| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load |
|
||||
|
||||
---
|
||||
|
||||
@@ -167,3 +172,4 @@ docker run -d \
|
||||
- Keep dependencies updated
|
||||
- The project uses `husky` + `lint-staged` for pre-commit checks
|
||||
- CI pipeline runs ESLint security rules on every push
|
||||
- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`)
|
||||
|
||||
314
llm.txt
314
llm.txt
@@ -1,6 +1,6 @@
|
||||
# OmniRoute
|
||||
|
||||
> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 67+ AI providers — all through a single OpenAI-compatible endpoint.
|
||||
> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 60+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (25 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -8,20 +8,22 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
|
||||
|
||||
**Key value:** One endpoint (`http://localhost:20128/v1`), unlimited models, zero downtime, minimal cost.
|
||||
|
||||
**Current version:** 3.0.0
|
||||
**Current version:** 3.4.2
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Runtime:** Node.js >= 18
|
||||
- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
|
||||
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
|
||||
- **Database:** SQLite via better-sqlite3 (local, zero-config)
|
||||
- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
|
||||
- **State management:** Zustand (client), SQLite (server persistence)
|
||||
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
|
||||
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
|
||||
- **Schemas:** Zod v4 for all API / MCP input validation
|
||||
- **Background jobs:** Custom token health check scheduler, 24h model auto-sync
|
||||
- **Streaming:** Server-Sent Events (SSE) for real-time proxy responses
|
||||
- **Proxy engine:** Custom pipeline with format translation, circuit breaker, rate limiting, auto-combo engine
|
||||
- **i18n:** next-intl with 30 languages
|
||||
- **Desktop:** Electron (cross-platform: Windows, macOS, Linux)
|
||||
- **Package:** Published on npm (`omniroute`) and Docker Hub (`diegosouzapw/omniroute`)
|
||||
|
||||
## Project Structure
|
||||
@@ -35,6 +37,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
|
||||
│ │ │ ├── agents/ # ACP Agents dashboard (CLI agent detection + custom agents)
|
||||
│ │ │ ├── analytics/ # Usage analytics and charts
|
||||
│ │ │ ├── api-manager/ # API key management
|
||||
│ │ │ ├── audit/ # Audit logs
|
||||
│ │ │ ├── auto-combo/ # Auto-combo engine dashboard
|
||||
│ │ │ ├── cache/ # Cache dashboard (semantic cache stats)
|
||||
│ │ │ ├── cli-tools/ # CLI tool configuration (Claude Code, Codex, Gemini CLI, etc.)
|
||||
│ │ │ ├── combos/ # Model combo management (9 strategies + 4 templates)
|
||||
│ │ │ ├── costs/ # Cost tracking per provider/model
|
||||
@@ -43,38 +48,130 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
|
||||
│ │ │ ├── limits/ # Rate limits dashboard
|
||||
│ │ │ ├── logs/ # Request, Proxy, Audit, Console logs (tabbed)
|
||||
│ │ │ ├── media/ # Image/video/music generation + transcription
|
||||
│ │ │ ├── memory/ # Memory system dashboard
|
||||
│ │ │ ├── onboarding/ # Onboarding wizard
|
||||
│ │ │ ├── playground/ # Model playground (Monaco editor, streaming)
|
||||
│ │ │ ├── providers/ # Provider management (OAuth + API key + free)
|
||||
│ │ │ ├── search-tools/ # Search tools configuration
|
||||
│ │ │ ├── settings/ # Settings tabs (General, Appearance, Security, Routing, Resilience, Advanced)
|
||||
│ │ │ ├── skills/ # Skills system dashboard
|
||||
│ │ │ ├── translator/ # Format translator + debug tools
|
||||
│ │ │ └── usage/ # Usage history
|
||||
│ │ ├── api/ # REST API endpoints
|
||||
│ │ │ ├── v1/ # OpenAI-compatible API (chat, models, embeddings, images, audio)
|
||||
│ │ ├── api/ # REST API endpoints (51 route directories)
|
||||
│ │ │ ├── v1/ # OpenAI-compatible API (chat, completions, models, embeddings,
|
||||
│ │ │ │ # images, audio, videos, music, moderations, rerank, search,
|
||||
│ │ │ │ # responses, messages, registered-keys, quotas, accounts)
|
||||
│ │ │ ├── v1beta/ # Gemini-compatible API
|
||||
│ │ │ ├── a2a/ # A2A agent management API
|
||||
│ │ │ ├── acp/ # ACP agent management API
|
||||
│ │ │ ├── oauth/ # OAuth flows per provider
|
||||
│ │ │ ├── providers/ # Provider CRUD and batch testing
|
||||
│ │ │ ├── models/ # Dashboard model listing and aliases
|
||||
│ │ │ ├── combos/ # Combo CRUD (multi-model fallback chains)
|
||||
│ │ │ └── ... # Other endpoints (usage, logs, health, settings, etc.)
|
||||
│ │ └── login/ # Login page
|
||||
│ ├── domain/ # Domain types and business logic interfaces
|
||||
│ │ │ ├── memory/ # Memory system API
|
||||
│ │ │ ├── skills/ # Skills system API
|
||||
│ │ │ ├── evals/ # Eval runner API
|
||||
│ │ │ ├── mcp/ # MCP HTTP transport API
|
||||
│ │ │ ├── search/ # Search provider API
|
||||
│ │ │ ├── webhooks/ # Webhook management
|
||||
│ │ │ ├── tunnels/ # Cloudflare tunnel management
|
||||
│ │ │ └── ... # Other endpoints (usage, logs, health, settings, pricing, etc.)
|
||||
│ │ ├── landing/ # Landing page
|
||||
│ │ ├── login/ # Login page
|
||||
│ │ ├── forgot-password/ # Password recovery
|
||||
│ │ ├── status/ # Status page
|
||||
│ │ └── docs/ # In-app documentation
|
||||
│ ├── domain/ # Domain types and policy engine
|
||||
│ │ ├── policyEngine.ts # Central policy engine
|
||||
│ │ ├── comboResolver.ts # Combo resolution logic
|
||||
│ │ ├── costRules.ts # Cost calculation rules
|
||||
│ │ ├── degradation.ts # Graceful degradation
|
||||
│ │ ├── fallbackPolicy.ts # Fallback behavior
|
||||
│ │ ├── lockoutPolicy.ts # Account lockout logic
|
||||
│ │ ├── modelAvailability.ts # Model availability checks
|
||||
│ │ ├── providerExpiration.ts # Provider credential expiration
|
||||
│ │ ├── quotaCache.ts # Quota caching layer
|
||||
│ │ ├── configAudit.ts # Configuration auditing
|
||||
│ │ └── responses.ts # Domain response types
|
||||
│ ├── i18n/ # Internationalization
|
||||
│ │ └── messages/ # 30 language JSON files
|
||||
│ ├── lib/ # Core libraries
|
||||
│ │ ├── a2a/ # Agent-to-Agent v0.3 protocol server
|
||||
│ │ ├── acp/ # ACP agent registry and manager (14 built-in + custom)
|
||||
│ │ ├── db/ # SQLite database layer (core, providers, models, combos, apiKeys, settings, backup)
|
||||
│ │ │ ├── skills/ # A2A skills (quotaManagement, smartRouting)
|
||||
│ │ │ ├── taskManager.ts # Task lifecycle with TTL cleanup
|
||||
│ │ │ └── streaming.ts # SSE streaming for A2A
|
||||
│ │ ├── acp/ # Agent Communication Protocol registry and manager
|
||||
│ │ ├── compliance/ # Compliance policy engine
|
||||
│ │ ├── db/ # SQLite database layer (21 modules + migrations)
|
||||
│ │ │ ├── core.ts # Database initialization, connection, schema
|
||||
│ │ │ ├── providers.ts # Provider connection CRUD
|
||||
│ │ │ ├── models.ts # Model catalog management
|
||||
│ │ │ ├── combos.ts # Combo configuration
|
||||
│ │ │ ├── apiKeys.ts # API key management
|
||||
│ │ │ ├── settings.ts # Settings persistence
|
||||
│ │ │ ├── backup.ts # Database backup/restore
|
||||
│ │ │ ├── proxies.ts # Proxy registry
|
||||
│ │ │ ├── prompts.ts # Prompt templates
|
||||
│ │ │ ├── webhooks.ts # Webhook subscriptions
|
||||
│ │ │ ├── detailedLogs.ts # Detailed request logging
|
||||
│ │ │ ├── domainState.ts # Domain state persistence
|
||||
│ │ │ ├── registeredKeys.ts # Registered API keys with quotas
|
||||
│ │ │ ├── quotaSnapshots.ts # Quota snapshot history
|
||||
│ │ │ ├── modelComboMappings.ts # Model-to-combo mappings
|
||||
│ │ │ ├── cliToolState.ts # CLI tool state tracking
|
||||
│ │ │ ├── encryption.ts # Data encryption
|
||||
│ │ │ ├── readCache.ts # Read-through cache layer
|
||||
│ │ │ ├── secrets.ts # Secrets management
|
||||
│ │ │ ├── stateReset.ts # State reset utilities
|
||||
│ │ │ ├── migrationRunner.ts # Schema migration runner
|
||||
│ │ │ └── migrations/ # 16 SQL migration files
|
||||
│ │ ├── evals/ # Eval runner and scheduler
|
||||
│ │ ├── memory/ # Persistent conversational memory
|
||||
│ │ │ ├── extraction.ts # Memory extraction from conversations
|
||||
│ │ │ ├── injection.ts # Memory injection into context
|
||||
│ │ │ ├── retrieval.ts # Memory retrieval/search
|
||||
│ │ │ ├── store.ts # Memory persistence layer
|
||||
│ │ │ └── summarization.ts # Memory summarization
|
||||
│ │ ├── oauth/ # OAuth providers, services, and utilities
|
||||
│ │ │ ├── constants/ # Default OAuth credentials (overridable via env)
|
||||
│ │ │ ├── providers/ # Provider-specific OAuth configs
|
||||
│ │ │ ├── services/ # Provider-specific token exchange logic
|
||||
│ │ │ └── utils/ # PKCE, callback server, token helpers
|
||||
│ │ ├── plugins/ # Plugin system
|
||||
│ │ ├── skills/ # Extensible skill framework
|
||||
│ │ │ ├── registry.ts # Skill registration
|
||||
│ │ │ ├── executor.ts # Skill execution engine
|
||||
│ │ │ ├── sandbox.ts # Skill sandbox environment
|
||||
│ │ │ ├── builtin/ # Built-in skills
|
||||
│ │ │ ├── interception.ts # Skill request interception
|
||||
│ │ │ └── injection.ts # Skill context injection
|
||||
│ │ ├── usage/ # Usage tracking system
|
||||
│ │ │ ├── callLogs.ts # Call log persistence
|
||||
│ │ │ ├── costCalculator.ts # Cost calculation engine
|
||||
│ │ │ └── usageHistory.ts # Usage history queries
|
||||
│ │ ├── cloudSync.ts # Cloud sync via Cloudflare Workers
|
||||
│ │ ├── cloudflaredTunnel.ts # Cloudflare tunnel management
|
||||
│ │ ├── pricingSync.ts # LiteLLM pricing data sync
|
||||
│ │ ├── semanticCache.ts # Semantic caching layer
|
||||
│ │ ├── tokenHealthCheck.ts # Background OAuth token refresh scheduler
|
||||
│ │ ├── webhookDispatcher.ts # Webhook event dispatcher
|
||||
│ │ └── localDb.ts # Unified re-export layer for all DB modules
|
||||
│ ├── middleware/ # Request middleware
|
||||
│ │ └── promptInjectionGuard.ts # Prompt injection detection
|
||||
│ ├── mitm/ # MITM proxy capability
|
||||
│ │ ├── cert/ # Certificate management
|
||||
│ │ ├── dns/ # DNS handling
|
||||
│ │ ├── targets/ # Target routing
|
||||
│ │ └── manager.ts # MITM proxy manager
|
||||
│ ├── shared/ # Shared utilities, components, and constants
|
||||
│ │ ├── components/ # Reusable UI components (Card, Badge, Button, Modal, Sidebar, ProviderIcon, etc.)
|
||||
│ │ ├── constants/ # Provider definitions, model lists, pricing, upstream headers
|
||||
│ │ ├── constants/ # Provider definitions (60+), model lists, pricing, routing strategies, MCP scopes
|
||||
│ │ ├── contracts/ # Shared API contracts
|
||||
│ │ ├── hooks/ # React hooks
|
||||
│ │ ├── middleware/ # Shared middleware utilities
|
||||
│ │ ├── schemas/ # Shared Zod schemas
|
||||
│ │ ├── services/ # Shared services
|
||||
│ │ ├── types/ # Shared TypeScript types
|
||||
│ │ ├── validation/ # Zod schemas (settings, providers, routes)
|
||||
│ │ └── utils/ # Helpers (auth, CORS, error codes, machine ID)
|
||||
│ ├── sse/ # SSE proxy pipeline
|
||||
@@ -83,29 +180,109 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
|
||||
│ ├── store/ # Zustand client-side stores (theme, providers, etc.)
|
||||
│ └── types/ # TypeScript type definitions
|
||||
├── open-sse/ # Standalone SSE server (npm workspace)
|
||||
│ ├── config/ # Model registries (embedding, image, audio, rerank, moderation, CLI fingerprints)
|
||||
│ ├── handlers/ # Request handlers per API type (chat, responses, embeddings, images, audio, search)
|
||||
│ ├── mcp-server/ # Built-in MCP server (16 tools, 3 transports: stdio/SSE/streamable-HTTP)
|
||||
│ ├── services/ # Auto-combo engine (6-factor scoring, 4 mode packs, bandit exploration)
|
||||
│ └── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ↔ DeepSeek)
|
||||
├── tests/ # Test suites (926 assertions)
|
||||
│ ├── unit/ # Unit tests (32+ test files)
|
||||
│ └── integration/ # Integration tests
|
||||
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
|
||||
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
|
||||
│ ├── executors/ # Provider-specific request executors (14 executors)
|
||||
│ │ ├── base.ts # Base executor with shared logic
|
||||
│ │ ├── default.ts # Default OpenAI-compatible executor
|
||||
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
|
||||
│ │ ├── codex.ts # OpenAI Codex CLI
|
||||
│ │ ├── antigravity.ts # Antigravity IDE
|
||||
│ │ ├── github.ts # GitHub Copilot
|
||||
│ │ ├── gemini-cli.ts # Gemini CLI
|
||||
│ │ ├── kiro.ts # Kiro AI
|
||||
│ │ ├── qoder.ts # Qoder AI
|
||||
│ │ ├── vertex.ts # Vertex AI (Service Account JSON)
|
||||
│ │ ├── cloudflare-ai.ts # Cloudflare Workers AI
|
||||
│ │ ├── opencode.ts # OpenCode Zen/Go
|
||||
│ │ ├── pollinations.ts # Pollinations AI
|
||||
│ │ └── puter.ts # Puter AI
|
||||
│ ├── handlers/ # Request handlers per API type (11 handlers)
|
||||
│ │ ├── chatCore.ts # Main chat completions handler
|
||||
│ │ ├── responsesHandler.ts # OpenAI Responses API handler
|
||||
│ │ ├── embeddings.ts # Embedding generation
|
||||
│ │ ├── imageGeneration.ts # Image generation (DALL-E, FLUX, SD, etc.)
|
||||
│ │ ├── videoGeneration.ts # Video generation
|
||||
│ │ ├── musicGeneration.ts # Music generation
|
||||
│ │ ├── audioSpeech.ts # Text-to-speech
|
||||
│ │ ├── audioTranscription.ts # Speech-to-text (Whisper, Deepgram, AssemblyAI)
|
||||
│ │ ├── moderations.ts # Content moderation
|
||||
│ │ ├── rerank.ts # Reranking API
|
||||
│ │ └── search.ts # Web search API
|
||||
│ ├── mcp-server/ # Built-in MCP server (25 tools, 3 transports: stdio/SSE/streamable-HTTP)
|
||||
│ │ ├── server.ts # MCP server core (tool registration, scope enforcement)
|
||||
│ │ ├── tools/ # Tool implementations (advancedTools, memoryTools, skillTools)
|
||||
│ │ ├── schemas/ # Zod input schemas (tools, audit, a2a)
|
||||
│ │ ├── scopeEnforcement.ts # Scope-based access control (10 scopes)
|
||||
│ │ ├── audit.ts # Tool call audit logging
|
||||
│ │ ├── runtimeHeartbeat.ts # MCP runtime heartbeat
|
||||
│ │ └── httpTransport.ts # HTTP transport handler
|
||||
│ ├── services/ # 36+ service modules
|
||||
│ │ ├── combo.ts # Core routing engine
|
||||
│ │ ├── usage.ts # Usage tracking
|
||||
│ │ ├── tokenRefresh.ts # OAuth token refresh
|
||||
│ │ ├── rateLimitManager.ts # Rate limit management
|
||||
│ │ ├── accountFallback.ts # Multi-account fallback
|
||||
│ │ ├── sessionManager.ts # Session management
|
||||
│ │ ├── wildcardRouter.ts # Wildcard model routing
|
||||
│ │ ├── autoCombo/ # Auto-combo engine (6-factor scoring, bandit exploration)
|
||||
│ │ ├── intentClassifier.ts # Request intent classification
|
||||
│ │ ├── taskAwareRouter.ts # Task-aware routing
|
||||
│ │ ├── thinkingBudget.ts # Thinking budget management
|
||||
│ │ ├── contextManager.ts # Context window management
|
||||
│ │ ├── modelDeprecation.ts # Model deprecation handling
|
||||
│ │ ├── modelFamilyFallback.ts # Intra-family model fallback
|
||||
│ │ ├── emergencyFallback.ts # Emergency fallback
|
||||
│ │ ├── workflowFSM.ts # Workflow state machine
|
||||
│ │ ├── backgroundTaskDetector.ts # Background task detection
|
||||
│ │ ├── ipFilter.ts # IP-based access control
|
||||
│ │ ├── signatureCache.ts # CLI signature caching
|
||||
│ │ ├── volumeDetector.ts # Request volume detection
|
||||
│ │ └── ... # Additional services (16 more modules)
|
||||
│ ├── transformer/ # Responses API transformer
|
||||
│ │ └── responsesTransformer.ts
|
||||
│ ├── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ↔ DeepSeek)
|
||||
│ │ ├── request/ # Request translators per provider
|
||||
│ │ ├── response/ # Response translators per provider
|
||||
│ │ ├── helpers/ # Translation helpers
|
||||
│ │ └── image/ # Image format translation
|
||||
│ └── utils/ # 22 utility modules (stream, TLS, proxy, logging, etc.)
|
||||
├── electron/ # Electron desktop app (cross-platform)
|
||||
│ ├── main.js # Electron main process
|
||||
│ ├── preload.js # Preload script (IPC bridge)
|
||||
│ └── assets/ # App icons and assets
|
||||
├── tests/ # Test suites
|
||||
│ ├── unit/ # 122 unit test files
|
||||
│ ├── integration/ # Integration tests
|
||||
│ ├── e2e/ # Playwright E2E tests
|
||||
│ ├── security/ # Security tests
|
||||
│ ├── translator/ # Translator-specific tests
|
||||
│ └── load/ # Load tests
|
||||
├── docs/ # Documentation
|
||||
│ ├── i18n/ # 30-language translated READMEs
|
||||
│ ├── screenshots/ # Dashboard screenshots
|
||||
│ ├── a2a-server.md # A2A agent protocol documentation
|
||||
│ ├── auto-combo.md # Auto-combo engine (6-factor scoring)
|
||||
│ └── mcp-server.md # MCP server (16 tools)
|
||||
│ ├── i18n/ # 30-language translated docs
|
||||
│ ├── ARCHITECTURE.md # Full architecture documentation
|
||||
│ ├── API_REFERENCE.md # API reference
|
||||
│ ├── USER_GUIDE.md # User guide
|
||||
│ ├── CODEBASE_DOCUMENTATION.md # Codebase overview
|
||||
│ ├── CLI-TOOLS.md # CLI tools integration guide
|
||||
│ ├── A2A-SERVER.md # A2A agent protocol documentation
|
||||
│ ├── AUTO-COMBO.md # Auto-combo engine (6-factor scoring)
|
||||
│ ├── MCP-SERVER.md # MCP server (25 tools)
|
||||
│ ├── TROUBLESHOOTING.md # Troubleshooting guide
|
||||
│ ├── VM_DEPLOYMENT_GUIDE.md # VPS deployment guide
|
||||
│ ├── openapi.yaml # OpenAPI specification
|
||||
│ └── screenshots/ # Dashboard screenshots
|
||||
├── bin/ # CLI entry points (omniroute, reset-password)
|
||||
├── scripts/ # Build and utility scripts
|
||||
└── .env.example # Environment variable template
|
||||
```
|
||||
|
||||
## Key Features (v3.0.0)
|
||||
## Key Features (v3.4.2)
|
||||
|
||||
### Core Proxy
|
||||
- **67+ AI providers** with automatic format translation
|
||||
- **6 routing strategies**: priority, weighted, round-robin, random, least-used, cost-optimized
|
||||
- **60+ AI providers** with automatic format translation
|
||||
- **4 provider categories**: Free (4), OAuth (8), API Key (48+), Custom (OpenAI/Anthropic-compatible)
|
||||
- **9 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random
|
||||
- **4-tier fallback**: Subscription → API Key → Cheap → Free
|
||||
- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
|
||||
- **Semantic caching** with cache hit/miss headers
|
||||
@@ -114,50 +291,81 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
|
||||
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
|
||||
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
|
||||
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
|
||||
- **926 tests** with 0 failures
|
||||
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
|
||||
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
|
||||
- **Prompt Injection Guard**: Middleware-level prompt injection detection
|
||||
- **MITM Proxy**: Certificate management, DNS handling, and target routing
|
||||
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
|
||||
- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
|
||||
|
||||
### Security
|
||||
- **CodeQL security**: Fixed 10+ CodeQL alerts (polynomial-redos, insecure-randomness, shell-injection)
|
||||
- **Route validation**: All 176 API routes validated with Zod schemas + `validateBody()`
|
||||
- **Route validation**: All API routes validated with Zod v4 schemas + `validateBody()`
|
||||
- **omniModel tag sanitization**: Internal `<omniModel>` tags never leak to clients in SSE streams
|
||||
- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint to reduce bot detection
|
||||
- **CLI Fingerprint Matching** — Per-provider request signature matching
|
||||
- **Prompt injection guard** — Request middleware detection
|
||||
- **Provider constants validated at module load** via Zod (`src/shared/validation/providerSchema.ts`)
|
||||
- **PII sanitizer** — Sensitive data scrubbing in logs
|
||||
|
||||
### Dashboard Pages
|
||||
### Dashboard Pages (23 sections)
|
||||
- **Providers** — OAuth, API key, and free provider management with ProviderIcon SVG icons
|
||||
- **Combos** — Multi-model combo builder with 4 templates (Free Stack, High Availability, Cost Saver, Balanced) + 9 strategies
|
||||
- **Auto-Combo** — Auto-combo engine dashboard with scoring metrics
|
||||
- **Analytics** — Token consumption, cost, heatmaps, distributions
|
||||
- **Health** — Uptime, memory, latency percentiles, circuit breakers
|
||||
- **Logs** — Request, Proxy, Audit, Console (tabbed)
|
||||
- **Audit** — Audit trail and compliance logging
|
||||
- **Costs** — Cost tracking per provider/model
|
||||
- **Limits** — Rate limit monitoring
|
||||
- **Cache** — Semantic cache statistics and management
|
||||
- **CLI Tools** — One-click configuration for 10+ AI CLI tools
|
||||
- **CLI Agents** — Grid of 14+ built-in agents with ProviderIcon and install detection + custom agent registration
|
||||
- **Playground** — Test any model with Monaco editor, streaming responses
|
||||
- **Media** — Image/video/music generation (DALL-E, FLUX, etc.) + audio transcription (up to 2GB files)
|
||||
- **Search Tools** — Search provider configuration and testing
|
||||
- **Memory** — Memory system management and visualization
|
||||
- **Skills** — Skills framework management and execution
|
||||
- **Translator** — Format debugging: playground, chat tester, test bench, live monitor
|
||||
- **Settings** — General, Appearance (7 color themes), Security (TLS/CLI fingerprint, IP filter), Routing, Resilience, Advanced
|
||||
- **Endpoint** — Unified: Endpoint Proxy, MCP Server, A2A Server, API Endpoints (tabbed)
|
||||
- **Onboarding** — Setup wizard for new users
|
||||
- **Usage** — Usage history and analytics
|
||||
- **API Manager** — API key management with scoped permissions
|
||||
|
||||
### Protocol Support
|
||||
- **OpenAI-compatible** — `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/transcriptions`, `/v1/audio/speech`
|
||||
- **OpenAI-compatible** — `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/transcriptions`, `/v1/audio/speech`, `/v1/moderations`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`
|
||||
- **Anthropic** — `/v1/messages`, `/v1/messages/count_tokens`
|
||||
- **OpenAI Responses** — `/v1/responses`
|
||||
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
|
||||
- **Ollama** — `/v1/api/chat`, `/api/tags`
|
||||
- **MCP** — 16-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
|
||||
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
|
||||
- **MCP** — 25-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
|
||||
- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
|
||||
- **ACP** — Agent detection, custom agent registry
|
||||
- **ACP** — Agent Communication Protocol registry and manager
|
||||
|
||||
### MCP Server (16 Tools)
|
||||
### MCP Server (25 Tools)
|
||||
| Category | Tools |
|
||||
|-----------|-------|
|
||||
| Essential | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog` |
|
||||
| Advanced | `simulate_route`, `set_budget_guard`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot` |
|
||||
| Core (18) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `sync_pricing` |
|
||||
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
|
||||
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
|
||||
|
||||
**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
|
||||
|
||||
### Provider Categories
|
||||
|
||||
**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
|
||||
|
||||
**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
|
||||
|
||||
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
|
||||
|
||||
**Custom Providers:** OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) with custom base URLs
|
||||
|
||||
### Internationalization
|
||||
- 30 languages for UI (all dashboard pages)
|
||||
- 30 translated READMEs in docs/i18n/
|
||||
- 30 translated documentation sets in docs/i18n/
|
||||
- Language switcher in documentation
|
||||
|
||||
## Key Architectural Decisions
|
||||
@@ -172,16 +380,22 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
|
||||
|
||||
5. **SSE proxy pipeline:** The proxy pipeline is middleware-based: request → auth resolution → rate limiting → circuit breaker → format translation → upstream call → response translation → SSE streaming back to client.
|
||||
|
||||
6. **SQLite for persistence:** All state (providers, combos, logs, settings, API keys) stored in a single SQLite database. All DB operations go through `src/lib/db/` modules, never raw SQL in routes.
|
||||
6. **SQLite for persistence:** All state (providers, combos, logs, settings, API keys, memory, skills) stored in a single SQLite database via 21 domain-specific modules. All DB operations go through `src/lib/db/` modules, never raw SQL in routes.
|
||||
|
||||
7. **OAuth with PKCE:** OAuth flows use PKCE for security. Token refresh handled by background job (`tokenHealthCheck.ts`).
|
||||
|
||||
8. **ProviderIcon component:** Unified icon system using `@lobehub/icons` (130+ SVG) with PNG fallback and generic icon fallback chain. Used on providers, dashboard, and agents pages.
|
||||
|
||||
9. **DB architecture:** `localDb.ts` is a re-export layer only — real logic lives in `src/lib/db/` modules (core, providers, models, combos, apiKeys, settings, backup).
|
||||
9. **DB architecture:** `localDb.ts` is a re-export layer only — real logic lives in 21 `src/lib/db/` modules with 16 SQL migrations.
|
||||
|
||||
10. **Upstream headers:** Custom headers merged in executors after default auth; same header name replaces executor value. Forbidden header names in `src/shared/constants/upstreamHeaders.ts`.
|
||||
|
||||
11. **Memory/Skills cross-cutting systems:** Memory and Skills affect the MCP tools, request pipeline, and A2A skills. Memory provides persistent context across sessions; Skills provide extensible tool execution with sandbox isolation.
|
||||
|
||||
12. **Domain policy engine:** `src/domain/` contains policy engine modules (policyEngine, comboResolver, costRules, degradation, fallbackPolicy, lockoutPolicy, modelAvailability, providerExpiration, quotaCache, configAudit) that govern routing decisions independently from the pipeline.
|
||||
|
||||
13. **Provider constants validated at load:** All provider definitions validated via Zod schemas at module load time (`src/shared/validation/providerSchema.ts`). Invalid providers fail fast.
|
||||
|
||||
## Main Flows
|
||||
|
||||
### Proxy Request Flow
|
||||
@@ -196,6 +410,8 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
|
||||
9. Response translation: provider → OpenAI format
|
||||
10. omniModel tag sanitization (strip internal tags)
|
||||
11. SSE streaming back to client
|
||||
12. Memory extraction (if memory system enabled)
|
||||
13. Usage logging and cost calculation
|
||||
|
||||
### OAuth Flow
|
||||
1. Dashboard initiates `/api/oauth/[provider]/authorize`
|
||||
@@ -210,22 +426,32 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
|
||||
|
||||
2. **Provider IDs vs aliases:** Providers have both an ID (`claude`, `github`) and a short alias (`cc`, `gh`). Models are referenced as `alias/model-name` (e.g., `cc/claude-opus-4-6`).
|
||||
|
||||
3. **The `open-sse/` directory is a separate npm workspace** with its own config, handlers, and translators.
|
||||
3. **The `open-sse/` directory is a separate npm workspace** with its own config, handlers, executors, translators, and services.
|
||||
|
||||
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
|
||||
|
||||
5. **Database layer:** Operations go through `src/lib/db/` modules. `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
|
||||
5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
|
||||
|
||||
6. **Tests use Node.js built-in test runner:** 926 assertions across 32+ test files. Run `npm test`.
|
||||
6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
|
||||
|
||||
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
|
||||
|
||||
8. **ACP agents** are in `src/lib/acp/registry.ts` (14 built-in) with a 60s detection cache. Custom agents stored via settings DB.
|
||||
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
|
||||
|
||||
9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
|
||||
|
||||
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
|
||||
|
||||
11. **Electron desktop app** in `electron/` with main.js and preload.js. Build with `npm run electron:build` (supports Windows, macOS, Linux).
|
||||
|
||||
12. **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts`. Use `sync_pricing` MCP tool or API endpoint.
|
||||
|
||||
13. **Memory system** in `src/lib/memory/` provides extraction, injection, retrieval, summarization, and persistent store. Exposed via MCP memory tools and `/api/memory/ API.
|
||||
|
||||
14. **Skills system** in `src/lib/skills/` provides registry, executor, sandbox isolation, built-in skills, custom skill support, request interception, and context injection. Exposed via MCP skill tools and `/api/skills/` API.
|
||||
|
||||
15. **Zod v4** is used for all validation. Import from `zod` package. Provider schemas validated at module load time.
|
||||
|
||||
## Links
|
||||
|
||||
- Repository: https://github.com/diegosouzapw/OmniRoute
|
||||
|
||||
119
restart.sh
119
restart.sh
@@ -1,119 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
PORT=20128
|
||||
MAX_ATTEMPTS=3
|
||||
echo "🔄 Reiniciando aplicação na porta $PORT..."
|
||||
|
||||
# Função para matar processos pela porta
|
||||
kill_by_port() {
|
||||
local attempt=1
|
||||
|
||||
while [ $attempt -le $MAX_ATTEMPTS ]; do
|
||||
echo "Tentativa $attempt de $MAX_ATTEMPTS..."
|
||||
|
||||
# Tenta encontrar processos usando lsof
|
||||
PIDS=$(lsof -ti:$PORT 2>/dev/null)
|
||||
|
||||
if [ -z "$PIDS" ]; then
|
||||
echo "✓ Porta $PORT está livre"
|
||||
return 0
|
||||
fi
|
||||
|
||||
echo "🔴 Matando processos na porta $PORT: $PIDS"
|
||||
|
||||
# Tenta SIGTERM primeiro (mais gentil)
|
||||
if [ $attempt -eq 1 ]; then
|
||||
for PID in $PIDS; do
|
||||
kill $PID 2>/dev/null && echo " - SIGTERM enviado para PID $PID"
|
||||
done
|
||||
sleep 2
|
||||
else
|
||||
# Se não funcionou, usa SIGKILL (força)
|
||||
for PID in $PIDS; do
|
||||
kill -9 $PID 2>/dev/null && echo " - SIGKILL enviado para PID $PID"
|
||||
done
|
||||
sleep 1
|
||||
fi
|
||||
|
||||
# Fallback: tenta fuser se lsof não funcionou
|
||||
if command -v fuser >/dev/null 2>&1; then
|
||||
fuser -k -9 $PORT/tcp 2>/dev/null && echo " - fuser utilizado como fallback"
|
||||
sleep 1
|
||||
fi
|
||||
|
||||
attempt=$((attempt + 1))
|
||||
done
|
||||
|
||||
# Última verificação
|
||||
if lsof -ti:$PORT >/dev/null 2>&1; then
|
||||
echo "❌ Erro: Não foi possível liberar a porta $PORT após $MAX_ATTEMPTS tentativas"
|
||||
echo "Processos ainda ativos:"
|
||||
lsof -i:$PORT 2>/dev/null
|
||||
return 1
|
||||
fi
|
||||
|
||||
return 0
|
||||
}
|
||||
|
||||
# Executa a função de kill
|
||||
if ! kill_by_port; then
|
||||
echo ""
|
||||
echo "💡 Sugestão: Execute manualmente:"
|
||||
echo " sudo lsof -ti:$PORT | xargs kill -9"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "🧹 Limpando build anterior (.next)..."
|
||||
rm -rf .next
|
||||
|
||||
echo "🔨 Fazendo build limpo..."
|
||||
npm run build
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ Build falhou!"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
# Garante que a porta está livre antes de iniciar (build pode ter ocupado)
|
||||
fuser -k $PORT/tcp 2>/dev/null
|
||||
sleep 1
|
||||
|
||||
echo "🚀 Iniciando servidor na porta $PORT..."
|
||||
LOG_FILE="/tmp/omniroute.log"
|
||||
> "$LOG_FILE"
|
||||
|
||||
npx next start --port $PORT >> "$LOG_FILE" 2>&1 &
|
||||
SERVER_PID=$!
|
||||
|
||||
# Ao fechar (Ctrl+C), mata o servidor e libera a porta
|
||||
cleanup() {
|
||||
echo ""
|
||||
echo "🛑 Parando servidor (PID: $SERVER_PID)..."
|
||||
kill $SERVER_PID 2>/dev/null
|
||||
wait $SERVER_PID 2>/dev/null
|
||||
fuser -k $PORT/tcp 2>/dev/null
|
||||
echo "✅ Servidor parado. Porta $PORT liberada."
|
||||
exit 0
|
||||
}
|
||||
trap cleanup SIGINT SIGTERM
|
||||
|
||||
# Aguarda o servidor ficar pronto
|
||||
echo "⏳ Aguardando servidor iniciar (PID: $SERVER_PID)..."
|
||||
for i in $(seq 1 15); do
|
||||
sleep 1
|
||||
if curl -s -o /dev/null -w "" http://localhost:$PORT > /dev/null 2>&1; then
|
||||
echo ""
|
||||
echo "✅ Servidor rodando em http://localhost:$PORT (PID: $SERVER_PID)"
|
||||
echo "📄 Pressione Ctrl+C para parar"
|
||||
echo "────────────────────────────────────────"
|
||||
break
|
||||
fi
|
||||
printf "."
|
||||
done
|
||||
|
||||
# Fica mostrando os logs na tela até Ctrl+C
|
||||
tail -f "$LOG_FILE" &
|
||||
TAIL_PID=$!
|
||||
wait $SERVER_PID 2>/dev/null
|
||||
kill $TAIL_PID 2>/dev/null
|
||||
@@ -1,25 +0,0 @@
|
||||
import { openaiToOpenAIResponsesRequest } from "./open-sse/translator/request/openai-responses.ts";
|
||||
|
||||
const root = {
|
||||
model: "gpt-5.3-codex-xhigh",
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: "<system-reminder>\nThe following skills are available...",
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
try {
|
||||
// Let's modify the file to actually export the function throwing or we can just copy the original logic.
|
||||
// Actually, wait, let's just create a modified version of it here inline to see where it breaks.
|
||||
const result = openaiToOpenAIResponsesRequest("gpt-5.3-codex-xhigh", root, true, null);
|
||||
console.log("Result:", JSON.stringify(result, null, 2));
|
||||
} catch (e) {
|
||||
console.error("Test Error:", e);
|
||||
}
|
||||
207
test_out.txt
207
test_out.txt
@@ -1,207 +0,0 @@
|
||||
[CREDENTIALS] No external credentials file found, using defaults.
|
||||
[DB] SQLite database ready: /home/diegosouzapw/.omniroute/storage.sqlite
|
||||
[MODEL] Ambiguous model 'claude-haiku-4.5'. Use provider/model prefix (ex: gh/claude-haiku-4.5 or kr/claude-haiku-4.5). Candidates: gh, kr, anthropic
|
||||
TAP version 13
|
||||
# Subtest: getModelInfoCore resolves unique non-openai unprefixed model
|
||||
ok 1 - getModelInfoCore resolves unique non-openai unprefixed model
|
||||
---
|
||||
duration_ms: 3.403766
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: getModelInfoCore keeps openai fallback for gpt-4o
|
||||
ok 2 - getModelInfoCore keeps openai fallback for gpt-4o
|
||||
---
|
||||
duration_ms: 0.535726
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: getModelInfoCore resolves gpt-5.4 to codex
|
||||
ok 3 - getModelInfoCore resolves gpt-5.4 to codex
|
||||
---
|
||||
duration_ms: 0.321781
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: getModelInfoCore returns explicit ambiguity metadata for ambiguous unprefixed model
|
||||
ok 4 - getModelInfoCore returns explicit ambiguity metadata for ambiguous unprefixed model
|
||||
---
|
||||
duration_ms: 1.079896
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: getModelInfoCore canonicalizes github legacy alias with explicit provider prefix
|
||||
ok 5 - getModelInfoCore canonicalizes github legacy alias with explicit provider prefix
|
||||
---
|
||||
duration_ms: 0.370547
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: GithubExecutor routes codex-family model to /responses
|
||||
ok 6 - GithubExecutor routes codex-family model to /responses
|
||||
---
|
||||
duration_ms: 0.47113
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: GithubExecutor keeps non-codex model on /chat/completions
|
||||
ok 7 - GithubExecutor keeps non-codex model on /chat/completions
|
||||
---
|
||||
duration_ms: 0.38457
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: DefaultExecutor uses x-api-key for kimi-coding-apikey
|
||||
ok 8 - DefaultExecutor uses x-api-key for kimi-coding-apikey
|
||||
---
|
||||
duration_ms: 0.451443
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: CodexExecutor forces stream=true for upstream compatibility
|
||||
ok 9 - CodexExecutor forces stream=true for upstream compatibility
|
||||
---
|
||||
duration_ms: 1.203259
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: Claude native messages can be round-tripped through OpenAI into Claude OAuth format
|
||||
ok 10 - Claude native messages can be round-tripped through OpenAI into Claude OAuth format
|
||||
---
|
||||
duration_ms: 7.232512
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: CodexExecutor maps fast service tier to priority
|
||||
ok 11 - CodexExecutor maps fast service tier to priority
|
||||
---
|
||||
duration_ms: 0.489993
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: shouldUseNativeCodexPassthrough only enables responses-native Codex requests
|
||||
ok 12 - shouldUseNativeCodexPassthrough only enables responses-native Codex requests
|
||||
---
|
||||
duration_ms: 0.441911
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: CodexExecutor can force fast service tier from settings
|
||||
ok 13 - CodexExecutor can force fast service tier from settings
|
||||
---
|
||||
duration_ms: 0.299575
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: CodexExecutor always requests SSE accept header
|
||||
ok 14 - CodexExecutor always requests SSE accept header
|
||||
---
|
||||
duration_ms: 0.602914
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: CodexExecutor does not request SSE accept header for compact requests
|
||||
ok 15 - CodexExecutor does not request SSE accept header for compact requests
|
||||
---
|
||||
duration_ms: 0.322611
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: CodexExecutor preserves native responses payloads for Codex passthrough
|
||||
not ok 16 - CodexExecutor preserves native responses payloads for Codex passthrough
|
||||
---
|
||||
duration_ms: 1.856261
|
||||
type: 'test'
|
||||
location: '/home/diegosouzapw/dev/proxys/9router/tests/unit/plan3-p0.test.mjs:221:1'
|
||||
failureType: 'testCodeFailure'
|
||||
error: |-
|
||||
Expected values to be strictly equal:
|
||||
|
||||
false !== true
|
||||
|
||||
code: 'ERR_ASSERTION'
|
||||
name: 'AssertionError'
|
||||
expected: true
|
||||
actual: false
|
||||
operator: 'strictEqual'
|
||||
stack: |-
|
||||
TestContext.<anonymous> (file:///home/diegosouzapw/dev/proxys/9router/tests/unit/plan3-p0.test.mjs:242:10)
|
||||
Test.runInAsyncScope (node:async_hooks:214:14)
|
||||
Test.run (node:internal/test_runner/test:1047:25)
|
||||
Test.processPendingSubtests (node:internal/test_runner/test:744:18)
|
||||
Test.postRun (node:internal/test_runner/test:1173:19)
|
||||
Test.run (node:internal/test_runner/test:1101:12)
|
||||
async Test.processPendingSubtests (node:internal/test_runner/test:744:7)
|
||||
...
|
||||
# Subtest: CodexExecutor strips streaming fields for compact passthrough
|
||||
ok 17 - CodexExecutor strips streaming fields for compact passthrough
|
||||
---
|
||||
duration_ms: 0.296176
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: CodexExecutor routes responses subpaths to matching upstream paths
|
||||
ok 18 - CodexExecutor routes responses subpaths to matching upstream paths
|
||||
---
|
||||
duration_ms: 0.546657
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: translateNonStreamingResponse converts Responses API payload to OpenAI chat.completion
|
||||
ok 19 - translateNonStreamingResponse converts Responses API payload to OpenAI chat.completion
|
||||
---
|
||||
duration_ms: 1.483788
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: extractUsageFromResponse reads usage from Responses API payload
|
||||
ok 20 - extractUsageFromResponse reads usage from Responses API payload
|
||||
---
|
||||
duration_ms: 0.398039
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: detectFormat identifies OpenAI Responses when input is string
|
||||
ok 21 - detectFormat identifies OpenAI Responses when input is string
|
||||
---
|
||||
duration_ms: 0.359174
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: detectFormat identifies OpenAI Responses by max_output_tokens without input array
|
||||
ok 22 - detectFormat identifies OpenAI Responses by max_output_tokens without input array
|
||||
---
|
||||
duration_ms: 0.271215
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: detectFormatFromEndpoint forces OpenAI for /v1/chat/completions
|
||||
ok 23 - detectFormatFromEndpoint forces OpenAI for /v1/chat/completions
|
||||
---
|
||||
duration_ms: 0.52054
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: detectFormatFromEndpoint forces Claude for /v1/messages
|
||||
ok 24 - detectFormatFromEndpoint forces Claude for /v1/messages
|
||||
---
|
||||
duration_ms: 0.433035
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: translateRequest normalizes openai-responses input string into list payload
|
||||
ok 25 - translateRequest normalizes openai-responses input string into list payload
|
||||
---
|
||||
duration_ms: 0.358109
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: translateRequest preserves service_tier when converting openai to openai-responses
|
||||
ok 26 - translateRequest preserves service_tier when converting openai to openai-responses
|
||||
---
|
||||
duration_ms: 1.10454
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: parseSSEToResponsesOutput parses completed response from SSE payload
|
||||
ok 27 - parseSSEToResponsesOutput parses completed response from SSE payload
|
||||
---
|
||||
duration_ms: 0.575476
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: parseSSEToResponsesOutput returns null for invalid payload
|
||||
ok 28 - parseSSEToResponsesOutput returns null for invalid payload
|
||||
---
|
||||
duration_ms: 0.302714
|
||||
type: 'test'
|
||||
...
|
||||
# Subtest: parseSSEToOpenAIResponse merges split tool call chunks by id without duplication
|
||||
ok 29 - parseSSEToOpenAIResponse merges split tool call chunks by id without duplication
|
||||
---
|
||||
duration_ms: 0.916032
|
||||
type: 'test'
|
||||
...
|
||||
1..29
|
||||
# tests 29
|
||||
# suites 0
|
||||
# pass 28
|
||||
# fail 1
|
||||
# cancelled 0
|
||||
# skipped 0
|
||||
# todo 0
|
||||
# duration_ms 65.394285
|
||||
@@ -1,36 +0,0 @@
|
||||
import { getTargetFormat } from "./open-sse/services/provider.ts";
|
||||
import { parseModelFromRequest, resolveProviderAndModel } from "./open-sse/handlers/chatCore.ts"; // Since they're in chatCore directly?
|
||||
import { getProviderConfig } from "./open-sse/services/provider.ts";
|
||||
|
||||
const body = { model: "codex/gpt-5.3-codex-xhigh" };
|
||||
const parsedModel = body.model;
|
||||
|
||||
function resolveProviderAndModel(rawModel, providerFromPath = "") {
|
||||
let provider = providerFromPath;
|
||||
let model = rawModel;
|
||||
let resolvedAlias = null;
|
||||
|
||||
if (rawModel && rawModel.includes("/")) {
|
||||
const parts = rawModel.split("/");
|
||||
provider = parts[0];
|
||||
model = parts.slice(1).join("/");
|
||||
}
|
||||
|
||||
return { provider, model, resolvedAlias: null };
|
||||
}
|
||||
|
||||
const { provider, model, resolvedAlias } = resolveProviderAndModel(parsedModel, "");
|
||||
const effectiveModel = resolvedAlias || model;
|
||||
|
||||
const config = getProviderConfig(provider);
|
||||
const modelTargetFormat = config?.models?.find((m) => m.id === effectiveModel)?.targetFormat;
|
||||
const targetFormat = modelTargetFormat || getTargetFormat(provider);
|
||||
|
||||
console.log({
|
||||
provider,
|
||||
model,
|
||||
resolvedAlias,
|
||||
effectiveModel,
|
||||
modelTargetFormat,
|
||||
targetFormat,
|
||||
});
|
||||
@@ -1,51 +0,0 @@
|
||||
import { translateRequest } from "./open-sse/translator/index.ts";
|
||||
import { FORMATS } from "./open-sse/translator/formats.ts";
|
||||
import { CodexExecutor } from "./open-sse/executors/codex.ts";
|
||||
|
||||
const claudeCodeRequest = {
|
||||
model: "codex/gpt-5.3-codex-xhigh",
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: "What time is it?",
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
system: "Test system prompt",
|
||||
tools: [
|
||||
{
|
||||
name: "get_time",
|
||||
description: "Get the time",
|
||||
input_schema: {
|
||||
type: "object",
|
||||
properties: { timezone: { type: "string" } },
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
try {
|
||||
const result = translateRequest(
|
||||
FORMATS.CLAUDE,
|
||||
FORMATS.OPENAI_RESPONSES,
|
||||
"gpt-5.3-codex-xhigh",
|
||||
claudeCodeRequest,
|
||||
true, // stream
|
||||
null, // credentials
|
||||
"codex", // provider
|
||||
null, // reqLogger
|
||||
{ normalizeToolCallId: false, preserveDeveloperRole: true }
|
||||
);
|
||||
|
||||
const exec = new CodexExecutor();
|
||||
const finalBody = exec.transformRequest("gpt-5.3-codex-xhigh", result, true, {});
|
||||
|
||||
console.log("FINAL BODY:", JSON.stringify(finalBody, null, 2));
|
||||
} catch (err) {
|
||||
console.error("ERROR:");
|
||||
console.error(err);
|
||||
}
|
||||
@@ -1,8 +0,0 @@
|
||||
#!/bin/bash
|
||||
# Wrapper for OmniRoute translation validator
|
||||
# Provides easy CLI access to the Python validation script
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
# Run the Python script with all arguments
|
||||
exec python3 "$SCRIPT_DIR/scripts/validate_translation.py" "$@"
|
||||
Reference in New Issue
Block a user