From 8909ae041e512b80b40eb2e9dc71140694d142ab Mon Sep 17 00:00:00 2001 From: diegosouzapw Date: Sat, 7 Mar 2026 12:36:24 -0300 Subject: [PATCH] chore: update llm.txt to v2.0.13 state - Complete rewrite of llm.txt with current project structure - Added ACP agents, CLI fingerprint, sidebar reorganization - Added 30 languages, MCP/A2A servers, anti-ban features - Updated project structure tree with all dashboard pages --- llm.txt | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 104 insertions(+), 11 deletions(-) diff --git a/llm.txt b/llm.txt index 4dd5ba6944..ea5c8e0e01 100644 --- a/llm.txt +++ b/llm.txt @@ -8,6 +8,8 @@ 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:** 2.0.13 + ## Tech Stack - **Runtime:** Node.js >= 18 @@ -19,6 +21,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo - **Background jobs:** Custom token health check scheduler - **Streaming:** Server-Sent Events (SSE) for real-time proxy responses - **Proxy engine:** Custom pipeline with format translation, circuit breaker, rate limiting +- **i18n:** next-intl with 30 languages - **Package:** Published on npm (`omniroute`) and Docker Hub (`diegosouzapw/omniroute`) ## Project Structure @@ -27,9 +30,27 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo / ├── src/ # Main application source │ ├── app/ # Next.js App Router pages and API routes -│ │ ├── (dashboard)/ # Dashboard UI pages (providers, combos, analytics, logs, etc.) +│ │ ├── (dashboard)/ # Dashboard UI pages +│ │ │ └── dashboard/ +│ │ │ ├── agents/ # ACP Agents dashboard (CLI agent detection + custom agents) +│ │ │ ├── analytics/ # Usage analytics and charts +│ │ │ ├── api-manager/ # API key management +│ │ │ ├── cli-tools/ # CLI tool configuration (Claude, Codex, Gemini, etc.) +│ │ │ ├── combos/ # Model combo management +│ │ │ ├── costs/ # Cost tracking +│ │ │ ├── endpoint/ # Endpoint info and cloud proxy +│ │ │ ├── health/ # System health monitoring +│ │ │ ├── limits/ # Rate limits dashboard +│ │ │ ├── logs/ # Request logs viewer +│ │ │ ├── media/ # Image/video/music generation +│ │ │ ├── playground/ # Model playground (Monaco editor, streaming) +│ │ │ ├── providers/ # Provider management (OAuth + API key + free) +│ │ │ ├── settings/ # Settings tabs (General, Appearance, Security, Routing, Resilience, Advanced) +│ │ │ ├── translator/ # Format translator + debug tools +│ │ │ └── usage/ # Usage history │ │ ├── api/ # REST API endpoints │ │ │ ├── v1/ # OpenAI-compatible API (chat, models, embeddings, images, audio) +│ │ │ ├── acp/ # ACP agent management API │ │ │ ├── oauth/ # OAuth flows per provider (authorize, exchange, callback) │ │ │ ├── providers/ # Provider CRUD and batch testing │ │ │ ├── models/ # Dashboard model listing and aliases @@ -37,7 +58,10 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo │ │ │ └── ... # Other endpoints (usage, logs, health, settings, etc.) │ │ └── login/ # Login page │ ├── domain/ # Domain types and business logic interfaces +│ ├── i18n/ # Internationalization +│ │ └── messages/ # 30 language JSON files (ar, bg, da, de, en, es, fi, fr, he, hu, id, in, it, ja, ko, ms, nl, no, phi, pl, pt, pt-BR, ro, ru, sk, sv, th, uk-UA, vi, zh-CN) │ ├── lib/ # Core libraries +│ │ ├── acp/ # ACP agent registry and manager (14 built-in agents + custom) │ │ ├── db/ # SQLite database layer (providers, combos, prompts, logs) │ │ ├── oauth/ # OAuth providers, services, and utilities │ │ │ ├── providers/ # Provider-specific OAuth configs (GitHub, Google, Claude, etc.) @@ -47,28 +71,88 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo │ │ ├── tokenHealthCheck.ts # Background OAuth token refresh scheduler │ │ └── localDb.ts # Unified database access layer │ ├── shared/ # Shared utilities, components, and constants -│ │ ├── components/ # Reusable UI components (Card, Badge, Button, Modal, etc.) +│ │ ├── components/ # Reusable UI components (Card, Badge, Button, Modal, Sidebar, etc.) │ │ ├── constants/ # Provider definitions, model lists, pricing +│ │ ├── validation/ # Zod schemas (settings, providers, etc.) │ │ └── utils/ # Helpers (auth, CORS, error codes, machine ID) │ ├── sse/ # SSE proxy pipeline │ │ ├── services/ # Auth resolution, format translation, response handling │ │ └── middleware/ # Rate limiting, circuit breaker, caching, idempotency -│ ├── store/ # Zustand client-side stores +│ ├── store/ # Zustand client-side stores (theme, providers, etc.) │ ├── types/ # TypeScript type definitions │ ├── proxy.ts # Main proxy request handler │ └── server-init.ts # Server initialization (DB, health checks) ├── open-sse/ # Standalone SSE server (npm workspace) -│ ├── config/ # Model registries (embedding, image, audio, rerank, moderation) +│ ├── config/ # Model registries (embedding, image, audio, rerank, moderation, CLI fingerprints) │ ├── handlers/ # Request handlers per API type -│ └── translators/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses) +│ ├── mcp-server/ # Built-in MCP server (16 tools, audit logging, scope auth) +│ └── translators/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama) ├── tests/ # Test suites │ ├── unit/ # Unit tests (32+ test files) │ └── integration/ # Integration tests -├── docs/ # Documentation and screenshots +├── docs/ # Documentation (with 29-language i18n subdirectories) +│ ├── i18n/ # Translated docs (ar, bg, da, de, es, fi, fr, he, hu, id, in, it, ja, ko, ms, nl, no, phi, pl, pt, pt-BR, ro, ru, sk, sv, th, uk-UA, vi, zh-CN) +│ ├── 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) +├── electron/ # Electron desktop app ├── bin/ # CLI entry points (omniroute, reset-password) └── .env.example # Environment variable template ``` +## Key Features (v2.0.13) + +### Core Proxy +- **36+ AI providers** with automatic format translation +- **6 routing strategies**: priority, weighted, round-robin, random, least-used, cost-optimized +- **4-tier fallback**: Subscription → API Key → Cheap → Free +- **Semantic caching** with cache hit/miss headers +- **Idempotency** with configurable dedup window +- **Circuit breaker** per provider with configurable thresholds + +### Anti-Ban Protection +- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint to reduce bot detection +- **CLI Fingerprint Matching** — Per-provider request signature matching (headers/body ordering) to match native CLI tools. Proxy IP is preserved. + +### Dashboard Pages +- **Providers** — OAuth, API key, and free provider management +- **Combos** — Multi-model fallback chain builder with templates +- **Analytics** — Token consumption, cost, heatmaps, distributions +- **Health** — Uptime, memory, latency percentiles, circuit breakers +- **Logs** — Real-time request log viewer with filtering +- **Costs** — Cost tracking per provider/model +- **Limits** — Rate limit monitoring +- **CLI Tools** — One-click configuration for 10+ AI CLI tools +- **CLI Agents** — Grid of 14 built-in agents with install detection + custom agent registration +- **Playground** — Test any model with Monaco editor, streaming responses +- **Media** — Image/video/music generation (DALL-E, FLUX, AnimateDiff, etc.) +- **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 API endpoint info + cloud proxy + +### Sidebar Organization +- **Main**: Home, Endpoints, API Manager, Providers, Combos, Costs, Analytics, Limits +- **CLI**: Tools, Agents +- **Debug**: Translator, Playground, Media +- **System**: Health, Logs, Settings +- **Help**: Docs, Issues + +### Protocol Support +- **OpenAI-compatible** — `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/transcriptions` +- **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 +- **A2A** — Agent-to-Agent protocol (smart-routing, quota-management skills) +- **ACP** — Agent detection, custom agent registry + +### Internationalization +- 30 languages for UI (sidebar, settings, agents, and all dashboard pages) +- 30 READMEs (root README.md + 29 translated README.*.md) +- 29 translated doc sets in docs/i18n/ + ## Key Architectural Decisions 1. **OpenAI-compatible API surface:** All incoming requests follow the OpenAI API format (`/v1/chat/completions`, `/v1/models`, etc.). This makes OmniRoute a drop-in replacement for any tool that supports custom OpenAI endpoints. @@ -77,13 +161,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo 3. **Connection-based provider model:** Providers are stored as "connections" in SQLite. Each connection has an `id`, `provider`, `authType` (oauth/apikey/free), `isActive` flag, and credentials. Multiple connections per provider are supported for multi-account rotation. -4. **Combo system for fallback:** Users create "combos" — ordered lists of `provider/model` pairs. The proxy tries each in order until one succeeds. Supports 6 strategies: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized. +4. **Combo system for fallback:** Users create "combos" — ordered lists of `provider/model` pairs. The proxy tries each in order until one succeeds. Supports 6 strategies. 5. **SSE proxy pipeline (`src/sse/`):** 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) is stored in a single SQLite database file at `data/omniroute.db`. This keeps the app self-contained and zero-config. -7. **OAuth with PKCE:** OAuth flows use PKCE for security. A local callback server (`src/lib/oauth/utils/server.ts`) handles the redirect. Token refresh is handled by a background job (`tokenHealthCheck.ts`). +7. **OAuth with PKCE:** OAuth flows use PKCE for security. A local callback server handles the redirect. Token refresh is handled by a background job (`tokenHealthCheck.ts`). + +8. **ACP Agent Registry:** 14 built-in CLI agents with dynamic detection and a 60-second cache. Custom agents can be added via dashboard or API, stored in settings DB. ## Main Flows @@ -94,9 +180,10 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo 4. For combos: iterate through models in fallback order 5. Auth resolution: get credentials for the target provider 6. Format translation: OpenAI → provider native format -7. Upstream request with circuit breaker and rate limiting -8. Response translation: provider → OpenAI format -9. SSE streaming back to client +7. CLI fingerprint matching (if enabled for provider) +8. Upstream request with circuit breaker and rate limiting +9. Response translation: provider → OpenAI format +10. SSE streaming back to client ### OAuth Flow 1. Dashboard initiates `/api/oauth/[provider]/authorize` @@ -125,6 +212,12 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo 7. **The proxy pipeline is in `src/sse/`**, not in `src/app/api/v1/`. The API routes in `src/app/api/v1/` delegate to the SSE server running on a separate Express instance. +8. **Sidebar sections:** Main nav, CLI (Tools + Agents), Debug (Translator + Playground + Media), System (Health + Logs + Settings), Help (Docs + Issues). + +9. **ACP agents** are in `src/lib/acp/registry.ts` (14 built-in) with a 60s detection cache. Custom agents stored via `src/shared/validation/settingsSchemas.ts`. + +10. **CLI fingerprint configs** are in `open-sse/config/cliFingerprints.ts`. They match native CLI request patterns per provider. + ## Links - Repository: https://github.com/diegosouzapw/OmniRoute